Accounting Module

A complete Domain-Driven Design (DDD) bounded context module built on the Backbone Framework. This module follows Clean Architecture principles with a schema-first approach where YAML schema files are the single source of truth.

📖 Full handbook: docs/ — philosophy, architecture (C4), maintainer & developer guides, contribution guide, glossary, and ADRs. This README is the quickstart; the handbook is the depth.

Architecture Overview

accounting/
├── schema/                          # SCHEMA DEFINITIONS (Single Source of Truth)
│   ├── models/                     # Entity schema definitions
│   │   ├── index.model.yaml       # Module configuration and shared types
│   │   └── {entity}.model.yaml    # Entity definitions
│   ├── hooks/                      # Event hooks and triggers
│   │   └── index.hook.yaml        # Events and scheduled jobs
│   ├── workflows/                  # Business workflows
│   │   └── README.md              # Workflow documentation
│   └── openapi/                    # OpenAPI specifications
│       └── index.openapi.yaml     # API documentation
│
├── src/                            # SOURCE CODE (Generated + Custom)
│   ├── domain/                    # Domain Layer (generated)
│   │   ├── entity/               # Entity implementations
│   │   ├── value_object/         # Value objects
│   │   ├── event/                # Domain events
│   │   └── mod.rs
│   │
│   ├── application/               # Application Layer (generated)
│   │   ├── {entity}_services.rs  # Application services
│   │   └── mod.rs
│   │
│   ├── infrastructure/            # Infrastructure Layer (generated)
│   │   ├── persistence/          # Repository implementations
│   │   │   └── postgres/
│   │   └── mod.rs
│   │
│   ├── presentation/              # Presentation Layer (generated)
│   │   ├── http/                 # REST handlers
│   │   ├── grpc/                 # gRPC services
│   │   └── mod.rs
│   │
│   └── lib.rs                    # Module entry point
│
├── migrations/                    # DATABASE MIGRATIONS
│   └── postgres/                 # PostgreSQL migrations (generated)
│
├── Cargo.toml                    # Dependencies
└── README.md                     # This file

Quick Start

1. Define Your Schema

Create entity schema files in schema/models/:

# schema/models/example.model.yaml
name: Example
table_name: examples
collection: examples

fields:
  id:
    type: uuid
    attributes: ["@id", "@default(uuid)"]
  name:
    type: string
    attributes: ["@required"]
    validation:
      min_length: 1
      max_length: 255
  description:
    type: text
    attributes: ["@nullable"]
  status:
    type: enum
    enum_values: [active, inactive, pending]
    attributes: ["@default(active)"]
  created_at:
    type: datetime
    attributes: ["@default(now)"]
  updated_at:
    type: datetime
    attributes: ["@default(now)", "@updated_at"]
  deleted_at:
    type: datetime
    attributes: ["@nullable", "@soft_delete"]

indexes:
  - name: idx_examples_status
    fields: [status]
  - name: idx_examples_created_at
    fields: [created_at]

permissions:
  create: ["admin", "editor"]
  read: ["admin", "editor", "viewer"]
  update: ["admin", "editor"]
  delete: ["admin"]

2. Generate Code

Run the schema generator to create all code from your schema:

# Validate the schema first
metaphor schema schema validate

# Generate everything
metaphor schema schema generate accounting --target all

# Or generate specific targets
metaphor schema schema generate accounting --target rust,sql
metaphor schema schema generate accounting --target handler,repository,events

The canonical CLI is metaphor (v0.2.0); schema codegen is the nested passthrough metaphor schema schema <op>. The backbone name used elsewhere is a local dev alias for the framework CLI. Note: the grpc, proto, and graphql generators are disabled in schema/models/index.model.yaml, so those targets currently produce nothing.

3. Run Migrations

# Run PostgreSQL migrations
sqlx migrate run --source migrations/postgres

4. Use the Module

use backbone_accounting::AccountingModule;

// Create module instance with builder pattern
let module = AccountingModule::builder()
    .with_database(pool)
    .build()?;

// Get routes
let routes = module.routes();

Schema Generation Targets

Standard CRUD Endpoints

Each entity automatically gets the 12 standard BackboneCrudHandler endpoints:

Guarded in production. Posted GL entities (Journal, JournalLine, Ledger, AccountingPost) are mounted read-only via create_guarded_accounting_routes — the only sanctioned GL writer is POST /accounting/posts (see ADR-002). Master/config entities keep full CRUD. JournalLine and ReconciliationItem are cascade children with no @audit_metadata, so their soft-delete family (soft_delete/restore/empty_trash/list_deleted) is not generated.

Development Workflow

Adding a New Entity

1. Create schema file: schema/models/{entity}.model.yaml
2. Run generator: metaphor schema schema generate accounting --target all
3. Create/run migrations: metaphor migration create {entity}
4. Register the new service in the AccountingModule builder (src/lib.rs)
5. Test endpoints

See the Maintainer Guide for the full add-a-feature walkthrough.

Modifying an Entity

1. Update the schema file
2. Generate a migration: metaphor migration create {change}
3. Regenerate code: metaphor schema schema generate accounting --target all
4. Run migrations

Custom Business Logic

Add custom logic in the generated service files. The generator preserves custom code in marked sections.

Testing

# Run all tests
cargo test --package backbone-accounting

# Run with database
DATABASE_URL=postgresql://... cargo test --package backbone-accounting

Configuration

Environment variables:

• DATABASE_URL - PostgreSQL connection string
• RUST_LOG - Log level (trace, debug, info, warn, error)

Dependencies

This module depends on:

• backbone-core - Core framework utilities
• backbone-orm - ORM and database traits
• backbone-auth - Authentication and authorization
• backbone-messaging - Event messaging

Documentation

The full handbook lives in docs/:

• Philosophy & motivation · Background & prior art · Technology & the why
• Architecture (C4) · Maintainer Guide · Developer Guide
• Extension Guide · Contributing · Glossary · ADRs
• Specs: BRD · PRD · FSD

License

Part of the Backbone Framework.