Skip to content

Architecture⚓︎

This document explains how DMS is structured. Our goal is to build a system that is simple to maintain, impossible to "break" through bad data, and ready to grow as we add AI and search features.

The Big Picture⚓︎

DMS follows a "Core-First" design. There is one single source of truth (dms-core) that owns all the rules. Everything else—apps, bots, or AI—must ask the Core for permission before seeing or changing data.

flowchart LR
    Core["🧠 dms-core"]

    subgraph Clients ["User Interfaces"]
        direction TB
        Web --> Mobile
    end

    subgraph Intelligence ["Integration"]
        direction TB
        Search --> AI --> Notify
    end

    Clients --> Core
    Core --> Intelligence

The Four System Layers⚓︎

1. The Core (dms-core)⚓︎

This is the "Brain" of the system. It is the only place where data lives and where rules are enforced.

  • Responsibility: Managing Topics, Decisions, and Lessons.
  • Security: It checks every request against our Permissions rules.
  • History: It records every change so we can't "cheat" the memory.

2. Integration Services⚓︎

These services "watch" the Core. When a decision is made, they react, but they never change the original data.

  • Notifications: Sends an email when a Topic you follow is decided.
  • Search: Indexes data so you can find old lessons quickly.
  • AI & Insights: Looks for patterns (like overconfidence) without touching the records.

3. The Clients (The Faces)⚓︎

These are the tools people actually touch. Because the Core is "smart," the clients can stay "dumb" and easy to build.

  • Web App: The primary way teams collaborate.
  • Mobile App: For quick updates on the go.
  • Admin Tools: For managing organizations and system health.

4. The Foundation (dms-infra)⚓︎

The "Plumbing." This includes Docker, cloud hosting, and deployment scripts. It has no "business logic"—it just keeps the lights on.

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

How Systems Talk⚓︎

We use two different "languages" for communication to keep things fast:

  • REST API (Writing): Used for Actions. When you "Make a Decision" or "Add a Reason," you are sending a command.
  • GraphQL (Reading): Used for Exploring. When you want to see a dashboard of all "Failed Expectations," GraphQL lets you pull exactly that data without extra noise.

Safety Guarantees⚓︎

To ensure the "Memory" is never corrupted, we follow these three laws:

  1. One Source: Only the Core can change data. No "backdoor" database edits.
  2. Never Forget: We use an Audit Log. Every edit leaves a permanent footprint.
  3. Immutable History: You can add new information, but you can never "delete" a past thought to make yourself look better.

Next Steps⚓︎