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