---
name: "Modules And Spec"
description: "Guide to module organisation and documentation standards"
depth: 2
links: ["../index.md", "./core-module-spec.md", "../design/structure.md"]
---

# Module Organization and Documentation

## Module Layout

The project is organized into nested Gradle modules under these top-level groups:

```text
:apps          — applications (cli, server, tui, worker, desktop)
:core          — domain logic (events, sessions, transitions, kernel, context,
                 inference, tools, artifacts, validation, approvals, router, config, risk)
:infrastructure — adapters (persistence, inference providers, tools, workflow, artifacts-cas)
:testing       — test suites (replay, contracts, kernel, integration, fixtures,
                 projections, transitions, approvals, deterministic)
```

## Documentation

Module specifications are maintained in AsciiDoc format under `docs/modules/`:

- `docs/modules/core/` — core module specs (.adoc)
- `docs/modules/infrastructure/` — infrastructure module specs (.adoc)
- `docs/modules/apps/` — application module specs (.adoc)
- `docs/modules/testing/` — testing module specs (.adoc)

These `.adoc` files are the authoritative source for module responsibilities,
invariants, boundaries, and contracts.

## Spec Template

Each module spec covers these sections:

1. purpose
2. responsibilities
3. non-responsibilities
4. invariants
5. public contracts
6. owned events
7. consumed events
8. state model
9. threading/concurrency model
10. failure semantics
11. replay semantics
12. persistence requirements
13. observability requirements
14. security boundaries
15. extension points
16. forbidden dependencies
17. open questions

## Module Dependency Rules

```
core modules may depend on:
- core:events (shared vocabulary)
- lower-level core modules

core modules may never depend on:
- infrastructure
- interfaces
- apps

infrastructure modules may depend on:
- core modules
- other infrastructure modules

apps may depend on:
- core modules
- infrastructure modules
```

No cross-core imports between sibling core modules (except `core:events` for
shared event types). Enforced by project convention.

## Architecture Decision Records

Major decisions are recorded under `docs/decisions/` as ADRs. See existing
records for the format.