Files
archie/docs/architecture/organisation.md
T
sam fd4420a038 docs(architecture): record decisions recovered from the pre-migration tracker
Eight approved decisions existed only as beads memories and were lost when
the tracker was removed. Recovered from a backup taken six minutes before
8bf0f6b and folded into the docs that own them, rather than a new document.

- migration-decisions: recorded position as of 2026-07-29, the deferred
  private-input-DTO compromise, and the agreed internal/app/{archied,
  agentworker} next step
- configuration: missing credential degrades a capability, only invalid
  config is fatal; config generation moves from install.sh to archied setup
- identity: the three-layer invariants/SOUL/representation model, and why
  a curator may only propose SOUL changes
- agent-system: the curator isolation invariant (curators are peers, never
  on a chat turn's critical path)
- messaging-and-work-intake: semantic search over messages is an explicit
  non-goal, with the measurements behind it
- safe-change-and-recovery: the /restart deadlock and lockout constraints
- plugins-and-extensions: dates the surprisal deferral

Also replaces the dead `**Beads issue:** archie-core-5d7` frontmatter across
all 12 documents with the GitHub issue it migrated to (#73), and rewrites
every other beads identifier to its issue number.
2026-08-09 18:10:12 +10:00

94 lines
2.6 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.
## 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.