Skip to content

docs(arc42): link to .domain instead of duplicating domain content #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JSdotNet merged 1 commit into from
Aug 4, 2026
Merged

docs(arc42): link to .domain instead of duplicating domain content #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 13 additions & 6 deletions .arc42/03-context-and-scope.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 7 additions & 1 deletion .arc42/05-building-block-view.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<context>/domain.md` —
this view does not restate domain responsibilities.

```mermaid
C4Container
title Container Diagram — Prompt Backlog
Expand Down
25 changes: 14 additions & 11 deletions .arc42/08-crosscutting-concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand Down
30 changes: 12 additions & 18 deletions .arc42/12-glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<context>/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

Expand All @@ -20,30 +22,22 @@ 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
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.