102 lines
3.1 KiB
Markdown
102 lines
3.1 KiB
Markdown
# Repository Organisation
|
|
|
|
**Status:** Approved
|
|
**Date:** 2026-07-28
|
|
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
|
|
|
|
## Target structure
|
|
|
|
Archie MUST be organised around cohesive application responsibilities:
|
|
|
|
```tree
|
|
cmd/
|
|
archied/
|
|
archie-agent/
|
|
|
|
internal/
|
|
domain/
|
|
<area>/
|
|
eventbus/
|
|
policy/
|
|
infrastructure/
|
|
configuration/
|
|
eventbus/
|
|
nats/
|
|
forge/
|
|
persistence/
|
|
<external-service>/
|
|
app/
|
|
archied/
|
|
agentworker/
|
|
|
|
plugins/
|
|
<plugin>/
|
|
deployments/
|
|
<supported-assembly>/
|
|
docs/
|
|
guides/
|
|
examples/
|
|
<copyable-example>/
|
|
extras/
|
|
<optional-extension>/
|
|
```
|
|
|
|
Domain names are chosen from application behaviour during package review.
|
|
Existing names MUST NOT be retained merely to reduce migration work.
|
|
|
|
## Domain areas
|
|
|
|
A domain owns one cohesive job performed by Archie. It contains that job's
|
|
language, state, rules, operations, commands, events, policy implementations,
|
|
runtime settings, and required service contracts.
|
|
|
|
Code that changes together SHOULD live together. Empty or ceremonial `entities`,
|
|
`repositories`, or `services` layers are prohibited.
|
|
|
|
## Application composition
|
|
|
|
`internal/app`:
|
|
|
|
- constructs domains and infrastructure implementations;
|
|
- translates external configuration into domain and plugin settings;
|
|
- connects commands, events, and shared contracts;
|
|
- starts services in dependency order;
|
|
- owns health aggregation and shutdown ordering.
|
|
|
|
`cmd/*` parses only process-level input and invokes the relevant application
|
|
composition package. It MUST NOT contain substantive wiring or act as a service
|
|
locator.
|
|
|
|
## Process boundaries
|
|
|
|
Archie begins as a modular monolith even when capabilities run in separate
|
|
processes. A domain becomes a separately deployed service only for a concrete
|
|
need such as security isolation, independent scaling, failure containment, or
|
|
independent operation.
|
|
|
|
Possible future extraction does not justify premature network protocols or
|
|
duplicated service scaffolding.
|
|
|
|
A new command is not a reason for a new binary. `cmd/` entries are process
|
|
boundaries: a binary earns its place when its surface fails independently of the
|
|
fleet, or when one process may need to run in more than one location, such as a
|
|
high-availability pair or across a NAT boundary. Operational commands over a
|
|
surface an existing binary already owns are subcommands of that binary. Offline
|
|
database maintenance belongs to `archie-state-store`, which owns the file and
|
|
its path layout, not to a new recovery binary.
|
|
|
|
## Optional and operational material
|
|
|
|
- `extras/<extension>` contains a maintained optional extension with real
|
|
behaviour. Core Archie MUST NOT import it, and removing `extras/` MUST NOT
|
|
prevent the core application from building or running.
|
|
- `deployments/<assembly>` contains a supported assembly, including deployment
|
|
definitions and concise operational instructions.
|
|
- `docs/guides/` contains handwritten explanation and links to generated
|
|
reference material.
|
|
- `examples/` contains copyable samples with explicit purpose, prerequisites,
|
|
and support expectations.
|
|
|
|
Supported assemblies SHOULD demonstrate that capabilities can be selected
|
|
independently.
|