Core-First Architecture

This document describes the intended system shape for DMS. The architecture should protect decision integrity, keep the product maintainable, and support search and insight features without weakening the core record.

The Big Picture

DMS follows a core-first design. One system owns the decision record, enforces the rules, and exposes trusted interfaces to everything else. Clients and supporting services are built around that core rather than around direct data access.

flowchart LR subgraph Clients ["Clients"] direction TB Web["Web App"] Mobile["Mobile App"] Admin["Admin Tools"] end Core["dms-core<br/>Authoritative decision record"] subgraph Services ["Supporting Services"] direction TB Search["Search"] Notify["Notifications"] Insights["Insights"] end subgraph Foundation ["Foundation"] direction TB Storage["Data Storage"] Ops["Operations"] end Web -->|commands and reads| Core Mobile -->|commands and reads| Core Admin -->|platform operations| Core Core -->|events and read models| Search Core -->|events| Notify Core -->|approved signals| Insights Core --> Storage Core --> Ops classDef client fill:#E3F2FD,stroke:#90CAF9,color:#123,stroke-width:1px; classDef core fill:#E8F5E9,stroke:#66BB6A,color:#123,stroke-width:1.5px; classDef service fill:#FFF3E0,stroke:#FFB74D,color:#333,stroke-width:1px; classDef infra fill:#ECEFF1,stroke:#90A4AE,color:#333,stroke-width:1px; class Web,Mobile,Admin client; class Core core; class Search,Notify,Insights service; class Storage,Ops infra;

The Four System Layers

1. The Core (dms-core)

The core is the authoritative system for the decision record. It is the only place where domain data is written and where domain rules are enforced.

• Responsibility: Manage Topics, Choices, Reasons, Decisions, Expectations, Outcomes, Reviews, and Lessons.
• Security: Enforce the authorization model and visibility rules on every request.
• History: Preserve a trustworthy record of meaningful changes.

2. Supporting Services

Supporting services consume events or read models from the core, but they do not own or rewrite domain data.

• Search: Help users find earlier Topics, decisions, and lessons.
• Notifications: Remind users when a Topic needs attention.
• Insights: Surface patterns and related records without becoming authors of human reasoning.

3. The Clients

Clients are the user-facing applications. They should remain thin, with business rules concentrated in the core.

• Web App: The primary way people work with Topics.
• Mobile App: A lighter client for updates and review.
• Admin Tools: Account and operational management outside the decision domain.

4. The Foundation (dms-infra)

The foundation supports deployment, hosting, storage, and operations. It carries no product-specific decision logic.

Write and Read Model

The design separates writes from reads:

• Write path: Clients send commands to the core to create or update the decision record.
• Read path: Clients query the core for Topic history, comparisons, dashboards, and search-driven views.
• Service path: Supporting services receive events or derived data from the core for search, notifications, and insight features.

This keeps the primary record simple while still allowing broader discovery and review features around it.

Repository Map

Repository	Focus	Current Status
dms-docs	Strategy, vision, and design	Active
dms-core	Backend, database, and API	Active
dms-infra	DevOps, cloud, and setup	Active
dms-web	User interface and UX	Planned

Safety Guarantees

The architecture is built around four guarantees:

1. One source of truth: Only the core can write domain data.
2. Full auditability: Every meaningful change leaves a trace.
3. Protected history: New information can be added, but past reasoning cannot be silently rewritten.
4. Bounded intelligence: Search and insight features can assist discovery, but they cannot make Decisions or author human reasoning.

Next Steps

• Read the Domain Model for the core entities and records.
• Read the Behavior for Topic stages and lifecycle rules.