diff --git a/.arc42/03-context-and-scope.md b/.arc42/03-context-and-scope.md index 4be6e5160..be7f8fa91 100644 --- a/.arc42/03-context-and-scope.md +++ b/.arc42/03-context-and-scope.md @@ -40,20 +40,27 @@ C4Context ### Domain boundary: Capture vs. Inbox -> TODO: Revisit and align this boundary with .domain once the domain chapters are available and the bounded-context split is finalized. +```meta +status: active +related: [".domain/context-map.md", ".domain/capture/domain.md#aggregate-capture", ".domain/inbox/domain.md#aggregate-inbox-item"] +``` The most important internal boundary distinguishes *how items enter* from *what -happens after arrival*: +happens after arrival*. Bounded-context ownership, the `ItemCaptured` published +language contract, and the DDD relationship semantics for this boundary are the +authority of `.domain/context-map.md`; this chapter only records the +architectural consequence: | Concern | Owner | |---|---| | How items enter the system (sources, polling, syncing) | **Capture** | | What happens to items after arrival (triage, classify, route) | **Inbox** | -Capture delivers normalized `InboxItem`s to the Inbox incoming queue. The current -recommendation keeps capture tightly coupled to Inbox as one pipeline -(raw input → triage → route), with an optional future split if capture tooling -becomes independently owned (tracked in +Capture delivers normalized `InboxItem`s to the Inbox incoming queue via the +`ItemCaptured` contract (see `.domain/capture/domain.md#domain-event-itemcaptured`). +The current recommendation keeps capture tightly coupled to Inbox as one +deployable pipeline (raw input → triage → route), with an optional future split +if capture tooling becomes independently owned (tracked in `.arc42/11-risks-and-technical-debt.md`). ## External Interfaces diff --git a/.arc42/05-building-block-view.md b/.arc42/05-building-block-view.md index b0f3ce3ff..49fce8583 100644 --- a/.arc42/05-building-block-view.md +++ b/.arc42/05-building-block-view.md @@ -11,9 +11,15 @@ the internal structure of each access channel. ```meta status: active -related: [".arc42/03-context-and-scope.md#access-channels-scope"] +related: [".arc42/03-context-and-scope.md#access-channels-scope", ".domain/context-map.md"] ``` +Container boundaries below are the deployable/runtime split; the domains they +serve (Capture, Inbox, Backlog Management, Second Brain, Monitoring, Technology +Stack, Dev PC Management, Repository Management) are defined in +`.domain/context-map.md` and each context's own `.domain//domain.md` — +this view does not restate domain responsibilities. + ```mermaid C4Container title Container Diagram — Prompt Backlog diff --git a/.arc42/08-crosscutting-concepts.md b/.arc42/08-crosscutting-concepts.md index df895fa85..92ef8cdac 100644 --- a/.arc42/08-crosscutting-concepts.md +++ b/.arc42/08-crosscutting-concepts.md @@ -65,21 +65,24 @@ follows the organization's OpenTelemetry guidance. ```meta status: active -related: [".arc42/12-glossary.md"] +related: [".arc42/12-glossary.md", ".domain/inbox/domain.md#aggregate-inbox-item", ".domain/backlog/domain.md#aggregate-backlog-entry", ".domain/second-brain/domain.md#aggregate-knowledge-note", ".domain/monitoring/domain.md#aggregate-progress-signal", ".domain/dev-pc-management/domain.md#aggregate-machine-registry", ".domain/repository-management/domain.md#aggregate-repository-registry", ".domain/technology-stack/domain.md#aggregate-technology-registry"] ``` -The vocabulary exchanged across all applications and domains: +The vocabulary exchanged across all applications and domains is owned per +bounded context in `.domain` (aggregate shape, invariants, and lifecycle) — this +chapter only names which types cross container boundaries and are therefore an +architectural concern: -| Type | Key fields | +| Type | Owning aggregate | |---|---| -| **InboxItem** | id, source, title, body_md, captured_at, received_at, status, tags[], source_metadata | -| **BacklogEntry** | id, repo_ids[], type, content_md, tags[], priority, sub_items[], github_issue_ids, cli_task_ids | -| **KnowledgeNote** | id, topic, project_refs[], body_md, tags[], linked_note_ids[], updated_at | -| **ProgressSignal** | item_id, repo_id, signal_type, detected_at, notes | -| **RoutingRule** | source patterns, tag patterns → repo mapping | -| **MachineRegistration** | machine_id, machine_name, os, ip, mac_address, status, last_heartbeat | -| **RepositoryRegistration** | repo_id, repo_name, local_path, default_branch, package_manifests[] | -| **TechBaseline** | tool_name, required_version, policy_level, rollout_status | +| **InboxItem** | `.domain/inbox/domain.md#aggregate-inbox-item` | +| **BacklogEntry** | `.domain/backlog/domain.md#aggregate-backlog-entry` | +| **KnowledgeNote** | `.domain/second-brain/domain.md#aggregate-knowledge-note` | +| **ProgressSignal** | `.domain/monitoring/domain.md#aggregate-progress-signal` | +| **RoutingRule** | Not yet modeled in `.domain` — tracked in `.arc42/11-risks-and-technical-debt.md` | +| **MachineRegistration** | `.domain/dev-pc-management/domain.md#aggregate-machine-registry` | +| **RepositoryRegistration** | `.domain/repository-management/domain.md#aggregate-repository-registry` | +| **TechBaseline** | `.domain/technology-stack/domain.md#aggregate-technology-registry` | The cloud service persists only sync-oriented state derived from these types (`SyncState`, `SyncPayload`, `WebhookEvents`, `GitHubWebhookConfig`, diff --git a/.arc42/12-glossary.md b/.arc42/12-glossary.md index 2f4040512..3e05c6f24 100644 --- a/.arc42/12-glossary.md +++ b/.arc42/12-glossary.md @@ -2,12 +2,14 @@ ```meta status: active -related: [".arc42/08-crosscutting-concepts.md#shared-data-types"] +related: [".arc42/08-crosscutting-concepts.md#shared-data-types", ".domain/context-map.md"] ``` -Ubiquitous terms used across Prompt Backlog. Domain-specific vocabulary is owned per -bounded context in `.domain`; this glossary lists the system-wide terms and shared -data types. Keep it aligned with the `.domain` ubiquitous language. +Ubiquitous terms used across Prompt Backlog. Domain-specific vocabulary (bounded +context names, aggregates, domain events) is owned by `.domain` — see +`.domain/context-map.md` for the subdomain landscape and each +`.domain//naming.md` for that context's canonical terms. This glossary +lists only system-wide architecture terms that don't belong to a single domain. ## Terms @@ -20,16 +22,15 @@ status: active | **Local-first** | Design approach where the desktop app owns canonical data and works fully offline; the cloud is additive, never required. | | **Standalone mode** | Desktop running without any cloud connection; all data local, GitHub sync direct via `gh` CLI. | | **Connected mode** | Desktop additionally syncing state to the cloud for phone access and webhook forwarding. | -| **Capture** | The domain covering all input sources that feed items into the system. | -| **Inbox** | The domain that triages, classifies, and routes captured items after arrival. | -| **Second Brain** | Knowledge domain organizing project knowledge using PARA (Projects, Areas, Resources, Archive). | -| **PARA** | Projects / Areas / Resources / Archive — the organizing structure for knowledge notes. | | **Dot-folder contract** | Scope-portable `.inbox/`, `.backlog/`, `.brain/` folders present at workspace, repo, and project levels. | | **Fetch worker** | A local desktop background job that polls an external source (YouTube, website, email, GitHub). | | **Thin cloud** | The principle that the cloud service only coordinates sync, forwards webhooks, pushes notifications, and hosts the PC registry — no domain data or fetching. | | **Last-write-wins** | Conflict policy where the most recent edit prevails; new items always create rather than overwrite. | | **WoL relay** | Wake-on-LAN relay in the cloud PC registry that can wake a registered sleeping/offline machine. | +For bounded-context names (Capture, Inbox, Second Brain, etc.) and their +business meaning, see `.domain/context-map.md#subdomain-landscape`. + ## Shared Data Types ```meta @@ -37,13 +38,6 @@ status: active related: [".arc42/08-crosscutting-concepts.md#shared-data-types"] ``` -| Type | Meaning | -|---|---| -| **InboxItem** | A captured, not-yet-routed item entering the inbox. | -| **BacklogEntry** | A refined work item, optionally spanning multiple repos and linked to GitHub issues. | -| **KnowledgeNote** | A knowledge/second-brain note linkable to backlog entries. | -| **ProgressSignal** | A detected progress/health signal feeding monitoring dashboards. | -| **RoutingRule** | A rule mapping source/tag patterns to a target repo. | -| **MachineRegistration** | A registered developer machine in the PC registry. | -| **RepositoryRegistration** | A tracked repository with local path and package manifests. | -| **TechBaseline** | A required tool/version baseline with rollout status. | +Cross-container data types and the aggregate that owns their shape are listed +in `.arc42/08-crosscutting-concepts.md#shared-data-types`, which links out to +the owning chapter in `.domain` for each type instead of restating fields here.