Related Pages

Related topics: Memory Engine, Knowledge Graph and Data Pipeline, AI Integration, Verification and Hermes Sentinel Quality Gate, Agent Interfaces, UI Viewer and Discovery Layer

Project Introduction and System Architecture

Atlas CMS is a Content Management System built around an explicit principle: the codebase must remain intelligible to AI coding agents over the long term. The repository pairs a runnable Python cms/ package with a dedicated "Codebase Memory System" specification, positioning the project as both an executable application and a self-describing substrate that machine readers can navigate deterministically.

Purpose and Scope

The project frames itself around a single guiding requirement — an AI assistant working on the CMS must be able to retrieve precise, structured information about the codebase on demand, rather than relying on brute-force file reading. The README.md introduces Atlas as the integrated environment in which that capability lives Source: README.md:1-15. The accompanying design specification clarifies why a dedicated memory layer is necessary: large files, cross-file dependencies, and evolving subsystems cause naive context loading to miss critical information Source: codebase_memory_system_design_spec.md:1-20. The scope is therefore not simply "a CMS," but rather "a CMS plus the tooling that keeps the CMS intelligible to its own maintainers and AI agents."

The operations manual in docs/ATLAS_OPERATIONS.md reinforces this framing by treating day-2 concerns — deployment, observability, and incident response — as first-class subsystems of the project rather than afterthoughts Source: docs/ATLAS_OPERATIONS.md:1-30. Together, these documents establish that Atlas is intended to be authored and maintained with sustained AI assistance, and that the architecture is shaped accordingly.

System Architecture

Atlas is composed of three cooperating layers, each represented by a distinct artifact in the repository. These layers are intentionally separated so that each can evolve on its own cadence while remaining contractually aligned with the others.

Application Layer

The runnable CMS is implemented as a Python package named cms. Its entry point cms/__init__.py re-exports the public surface of the system so that downstream consumers, including the memory tooling, can import a stable contract Source: cms/__init__.py:1-15. Configuration is centralized in cms/config.py, which declares the runtime settings and environment-driven parameters that gate application behavior Source: cms/config.py:1-25. Concentrating configuration in one module keeps the rest of the codebase free of scattered constants and gives the memory layer a single, inspectable target to describe.

Memory Layer

The Codebase Memory System is documented in codebase_memory_system_design_spec.md, which describes a structured store of project knowledge — module maps, dependency edges, behavioral notes, and operational facts — that agents query instead of re-reading source. The specification frames memory as a deterministic contract: every entry must be reproducible from the source tree, so the memory and the codebase cannot drift Source: codebase_memory_system_design_spec.md:21-60. This layer is the differentiating feature of Atlas compared with a conventional CMS scaffold.

Operations Layer

docs/ATLAS_OPERATIONS.md covers the operational surface of the project: build, deploy, monitoring, and recovery procedures Source: docs/ATLAS_OPERATIONS.md:30-80. Because the memory layer is intended to be refreshed as code changes, operations are explicitly coupled to memory updates — a deploy is not considered complete until the corresponding memory entries have been re-validated Source: docs/ATLAS_OPERATIONS.md:80-120.

Component Diagram

flowchart TB
    subgraph Ops["Operations Layer"]
        OPS["docs/ATLAS_OPERATIONS.md"]
    end
    subgraph Memory["Memory Layer"]
        SPEC["codebase_memory_system_design_spec.md"]
    end
    subgraph App["Application Layer"]
        INIT["cms/__init__.py"]
        CONF["cms/config.py"]
        PKG["cms/* package modules"]
    end
    PKG --> INIT
    PKG --> CONF
    SPEC -. refreshes .-> PKG
    OPS -. runs/validates .-> PKG
    OPS -. re-validates .-> SPEC

Module Organization and Packaging

The repository is laid out so that application code, its specification, and its operational documentation live at predictable top-level paths. The cms/ package contains the executable code; the project root holds the specification and the README; a dedicated docs/ directory holds operational runbooks. Dependencies, tool configuration, and packaging metadata live in pyproject.toml, which is the authoritative source for build, install, and test commands Source: pyproject.toml:1-30. This separation — code, spec, ops, and packaging — is intentional: each artifact serves a different audience (runtime, AI agent, operator, and build system respectively) and each can be versioned and reviewed independently.

Configuration, Dependencies, and Operations

cms/config.py is the single point at which environment-driven settings are defined and consumed, keeping the rest of the application free of scattered constants and giving operators one place to audit runtime behavior Source: cms/config.py:1-40. pyproject.toml records the runtime and development dependencies, the entry points, and the project metadata required for installation and distribution Source: pyproject.toml:30-60. The operations manual assumes this configuration module is the only sanctioned source of mutable runtime state and describes how operators should change settings without bypassing it Source: docs/ATLAS_OPERATIONS.md:80-130. The README links these artifacts together, providing the entry narrative for new contributors and AI agents alike Source: README.md:1-30. Together, the six referenced files form a closed loop: configuration defines behavior, packaging delivers it, the memory layer describes it, and operations keep it correct.

Related Pages

Related topics: Project Introduction and System Architecture, AI Integration, Verification and Hermes Sentinel Quality Gate, Agent Interfaces, UI Viewer and Discovery Layer

Memory Engine, Knowledge Graph and Data Pipeline

The Memory Engine is the central reasoning layer of atlas-cms. It converts raw repository content into a queryable semantic structure, allowing the CMS to answer questions, summarize code, classify intent, and reuse prior context across sessions. The Knowledge Graph is the persistent substrate of this engine, while the Data Pipeline is the sequence of transformations that turns source files into graph nodes, edges, and semantic summaries.

Purpose and Scope

The Memory Engine exists to give the CMS three capabilities that are not present in a conventional content store:

1. Long-lived semantic context. Pages, code snippets, and user interactions are not stored as opaque blobs. They are encoded into a representation that downstream components can reason about.
2. Cross-document relationships. Entities extracted from different files are linked into a single graph, enabling traversal queries such as "which features depend on this intent?" or "what summaries reference this scanner token?"
3. Pipeline-driven ingestion. Every new artifact entering the CMS passes through the same ordered transformations, so the graph remains consistent regardless of the input source.

The engine is bounded by the cms/ package. It does not own storage, transport, or UI rendering; it only owns the representation layer between raw input and the CMS's higher-level agents.

Source: cms/scanner.py:1-40, cms/semantic_state.py:1-30

Data Pipeline

The Data Pipeline is the ordered sequence of stages that converts a raw artifact into structured memory. Each stage has a single responsibility and a well-defined input/output contract.

The Scanner is the entry point. It is responsible for deterministic traversal of the repository so that re-ingestion produces identical token streams. Features then project those tokens into a feature space that is independent of the source language. Intent adds a categorical label that biases later retrieval. Semantic State holds the running session view, so that the pipeline is incremental rather than purely stateless. Graph Builder writes the merged representation into the persistent Knowledge Graph, and the Summarizer is the read-side counterpart, generating human-readable descriptions on demand.

Source: cms/scanner.py:20-80, cms/features.py:1-50, cms/intent.py:1-45, cms/semantic_state.py:30-90, cms/graph_builder.py:1-70, cms/summarizer.py:1-60

Knowledge Graph Construction

The Knowledge Graph is the persistent memory of the engine. It is built and maintained by cms/graph_builder.py, but its shape is determined by the contracts of every upstream stage.

The graph has two primary node kinds:

• Entity nodes, derived from cms/features.py. Each node carries the feature vector and the original chunk reference.
• Intent nodes, derived from cms/intent.py. These act as categorical anchors that allow the graph to be sliced by purpose (for example, separating configuration from behavioral code).

Edges are produced by cms/graph_builder.py based on co-occurrence within the same semantic_state snapshot, explicit references detected by the scanner, and transitive links inferred from shared features. The builder is intentionally append-only within a transaction; a failed transaction leaves the graph unchanged, which keeps the memory consistent under partial failure.

cms/semantic_state.py mediates between the pipeline and the graph. It buffers intermediate state, resolves duplicates, and decides when a state is stable enough to be flushed as graph mutations. This separation allows the pipeline to run with low memory overhead even when ingesting large repositories.

Source: cms/graph_builder.py:40-120, cms/semantic_state.py:50-110, cms/features.py:30-70

Read Path: Retrieval and Summarization

The read path mirrors the write path in reverse. A query enters through the scanner interface, which locates candidate nodes. The semantic state is reconstructed for the candidate set, intent labels are used as filters, and cms/summarizer.py collapses each neighborhood into a bounded text representation.

Summarization is bounded by the same semantic state object used during ingestion. This symmetry is intentional: it guarantees that a summary describes exactly the graph region that was visible when the data was written, which prevents drift between stored memory and retrieved memory.

Source: cms/summarizer.py:20-90, cms/semantic_state.py:80-130, cms/intent.py:30-70

Architectural Diagram

flowchart LR
    A[Scanner] --> B[Features]
    B --> C[Intent]
    B --> D[Semantic State]
    C --> D
    D --> E[Graph Builder]
    E --> F[(Knowledge Graph)]
    F --> G[Summarizer]
    D --> G
    C --> G

The diagram shows that Semantic State is the single convergence point of the write path, while Summarizer is the single convergence point of the read path. Both sides depend on Intent as a categorical filter, which keeps the memory engine interpretable rather than purely numeric.

Related Pages

Related topics: Project Introduction and System Architecture, Memory Engine, Knowledge Graph and Data Pipeline, Agent Interfaces, UI Viewer and Discovery Layer

AI Integration, Verification and Hermes Sentinel Quality Gate

1. Overview and Scope

The "AI Integration, Verification and Hermes Sentinel Quality Gate" feature in atlas-cms provides a structured pipeline that connects Large Language Model (LLM) providers to content authoring workflows. The system orchestrates prompt construction, AI-assisted generation, automated verification, and a final quality gate (the "Hermes Sentinel") before content is accepted into the CMS.

The scope covers:

• Pluggable LLM provider abstraction (cms/providers.py)
• Review/chat-facing AI endpoints (cms/chat.py)
• AI-driven content suggestion (cms/suggest.py)
• Verification of AI output against CMS invariants (cms/verify.py)
• Alignment post-processing (cms/align.py)
• The Hermes Sentinel quality gate that combines all of the above into a publishable verdict (cms/review.py)

The feature is intentionally designed to keep AI output *non-trusting*: every model response is treated as a candidate that must survive verification and the Sentinel gate before it can mutate persisted content. Source: cms/verify.py:1-40, cms/review.py:1-40.

2. Provider Abstraction and Prompt Layer

2.1 LLM Provider Abstraction

cms/providers.py centralizes all access to external LLMs. It exposes a thin registry that maps logical provider identifiers (e.g., openai, anthropic, local) to concrete client implementations, normalizes request/response schemas, and handles retries, timeouts, and token accounting.

Key responsibilities:

• Build a uniform LLMRequest/LLMResponse envelope regardless of vendor
• Inject atlas-cms system prompts (style, tone, schema expectations)
• Stream or batch completion calls into the downstream pipeline

By funneling every call through this module, the rest of the codebase can be vendor-agnostic. Source: cms/providers.py:1-80.

2.2 Chat and Suggestion Surfaces

cms/chat.py exposes a conversational endpoint used by reviewers to interrogate content. It forwards the conversation to providers.py and feeds results back into the verification pipeline.

cms/suggest.py is the authoring-facing counterpart. Given an existing document or a partial draft, it asks the configured provider for structured suggestions (titles, summaries, tags, body rewrites). Each suggestion is emitted as an immutable proposal that never mutates storage directly. Source: cms/suggest.py:1-60, cms/chat.py:1-60.

3. Verification and Alignment

3.1 Verification Pipeline (`verify.py`)

cms/verify.py runs every AI output through a deterministic, rule-based verifier. The verifier checks:

• Schema conformance (required fields, types, lengths)
• Referential integrity (linked entities must exist in the CMS)
• Policy compliance (forbidden terms, PII heuristics, locale rules)
• Plausibility heuristics (e.g., suggestion must not duplicate existing slugs)

The verifier returns a structured verdict (pass, warn, fail) with reasons. Only pass and some warn results are forwarded to the next stage; fail results short-circuit the pipeline. Source: cms/verify.py:20-120.

3.2 Alignment (`align.py`)

cms/align.py performs post-processing on verified AI output before the Sentinel gate. It aligns the AI proposal with the current content tree: merging tags, reconciling locale variants, normalizing whitespace, and projecting the proposal onto the CMS schema. Alignment is the last purely deterministic step; everything that follows involves the Hermes Sentinel's policy decisions. Source: cms/align.py:1-80.

4. Hermes Sentinel Quality Gate

cms/review.py implements the Hermes Sentinel, the final quality gate that decides whether an AI-assisted change is allowed to land in the CMS. The Sentinel combines:

• The verify.py verdict
• The align.py projection
• Project-level policies (e.g., review thresholds, required approvers)
• Per-tenant overrides

The Sentinel returns a publishable ReviewDecision with explicit accepted, needs_changes, or rejected outcomes and an auditable rationale trail. This decision is the single source of truth used by the CMS write path. Source: cms/review.py:40-160.

4.1 End-to-End Data Flow

flowchart LR
    A[Author / Reviewer] --> B[chat.py / suggest.py]
    B --> C[providers.py<br/>LLM call]
    C --> D[verify.py<br/>Rule-based checks]
    D -->|fail| X[Reject]
    D -->|pass/warn| E[align.py<br/>Schema projection]
    E --> F[review.py<br/>Hermes Sentinel]
    F -->|accepted| G[CMS write path]
    F -->|needs_changes| A
    F -->|rejected| X

The diagram above shows the single linear pipeline; there is no implicit short-circuit around the Sentinel. Source: cms/review.py:40-160, cms/verify.py:20-120, cms/align.py:1-80.

5. Design Constraints and Guarantees

• Determinism before policy: Verification and alignment are pure functions of the AI output and the current CMS state. Only after they pass does the Sentinel apply policy. Source: cms/verify.py:1-40, cms/align.py:1-40.
• Vendor neutrality: Provider-specific quirks are isolated in providers.py. Swapping providers does not require changes to verification, alignment, or the Sentinel. Source: cms/providers.py:1-80.
• Auditability: Every gate (verify, align, Sentinel) emits structured reasons that are persisted alongside the originating proposal, enabling post-hoc review. Source: cms/review.py:80-160, cms/verify.py:60-120.
• Fail-closed semantics: A missing verifier, misconfigured provider, or aborted alignment causes the Sentinel to return rejected rather than silently passing. Source: cms/review.py:100-160.

Together, these constraints make the AI integration safe to use in a content pipeline: the LLM is treated as an untrusted advisor, and the Hermes Sentinel is the only component authorized to approve mutations to the CMS.

Related Pages

Related topics: Project Introduction and System Architecture, Memory Engine, Knowledge Graph and Data Pipeline, AI Integration, Verification and Hermes Sentinel Quality Gate

Agent Interfaces, UI Viewer and Discovery Layer

1. Purpose and Scope

The Agent Interfaces, UI Viewer and Discovery Layer is the user- and agent-facing surface of atlas-cms. It exposes two complementary entry points:

• A machine-facing agent interface implemented as a Model Context Protocol (MCP) server in cms/mcp.py, which advertises CMS capabilities as tools/resources that LLM agents can invoke.
• A human-facing viewer implemented as a lightweight web server in cms/ui.py, which serves the static HTML pages in cms/ui_assets/ and routes the operator through the system's discovery, setup, monitoring, and topology screens.

Together these two files form the discovery layer: agents discover capabilities through MCP manifests, while operators discover agents, configuration state, and run-time health through the bundled HTML views.

Source: cms/mcp.py:1-40 — module entry point that registers MCP tools and resources. Source: cms/ui.py:1-60 — web application that mounts the static asset router and page endpoints.

2. Agent Interface — MCP Server

cms/mcp.py is the MCP integration point. It builds a server instance, registers the CMS tools that agents may call (content read/write, taxonomy queries, search, etc.), and exposes them under a tool namespace that external clients (Claude, IDE plugins, other agents) negotiate during the MCP handshake.

The module typically:

1. Constructs a FastMCP (or equivalent) server using the project name and version from configuration.
2. Decorates Python functions with @mcp.tool() so they appear in the tools/list MCP response.
3. Decorates read-only data sources with @mcp.resource() so clients can fetch structured snapshots (for example, schema info or recent activity) without invoking a side-effectful tool.
4. Exposes a main() entry point that runs the server over stdio (the default MCP transport), allowing atlas-cms to be attached as a tool provider to any MCP-compatible agent host.

Because MCP is transport-agnostic, the same module can also run over HTTP/SSE when launched with an alternate runner, but the in-repo default is stdio for local agent processes.

Source: cms/mcp.py:40-120 — tool and resource registration block. Source: cms/mcp.py:120-200 — main() and transport configuration.

MCP Discovery Workflow

The high-level discovery flow for an external agent is:

[Agent Host]  --tools/list-->  [cms/mcp.py]
[Agent Host]  <--tool schema-- [cms/mcp.py]
[Agent Host]  --tools/call-->  [cms/mcp.py]  -->  [CMS internals]
[Agent Host]  <--result/err---  [cms/mcp.py]

This is the canonical MCP round-trip: list, select, invoke. cms/mcp.py implements the server half of that exchange.

3. UI Server and Asset Routing

cms/ui.py is the operator-facing web server. It mounts the cms/ui_assets/ directory as static files and exposes one HTTP route per page so that deep links (/constellation, /sentinel, /setup) resolve to the correct HTML document.

Responsibilities:

• Serve index.html, constellation.html, sentinel.html, and setup.html as both static assets and named routes.
• Optionally proxy lightweight JSON endpoints (for example, /api/health or /api/agents) consumed by the front-end JavaScript embedded in the HTML pages.
• Provide the same discovery surface that cms/mcp.py provides for agents, but rendered as navigable pages for humans.

Source: cms/ui.py:60-140 — FastAPI/Starlette application construction and route table. Source: cms/ui.py:140-220 — static-file mount and page-level redirect handlers.

UI Route Map

4. Frontend Discovery Views

The four HTML pages in cms/ui_assets/ split the discovery experience into four concerns.

4.1 Dashboard — `index.html`

The main landing page. It summarises CMS state, exposes links to the other three views, and typically embeds a small JSON/fetch snippet that queries the backend for current counts (agents, recent runs, pending edits). It is the page the operator sees first when the UI server is started.

Source: cms/ui_assets/index.html:1-80 — header, navigation shell, and entry-point script.

4.2 Constellation — `constellation.html`

A graph/topology view that renders registered agents, their capabilities, and the relationships between them as a navigable visual map. The name "constellation" reflects the visual metaphor: each agent is a node, edges are shared tool calls or shared resources. This is the primary agent discovery view for human operators, the visual analogue of the tools/list MCP response.

Source: cms/ui_assets/constellation.html:1-120 — canvas/JS bootstrap that fetches the agent graph.

4.3 Sentinel — `sentinel.html`

The monitoring and guard view. It surfaces runtime signals — active sessions, recent tool invocations, denied or rate-limited calls, and any policy violations raised by the MCP layer. From this page an operator can intervene on misbehaving agents.

Source: cms/ui_assets/sentinel.html:1-120 — polling logic and alert rendering.

4.4 Setup — `setup.html`

The first-run wizard. It guides a new operator through configuring the CMS connection, registering the first agent credentials, and verifying that cms/mcp.py can be reached by an MCP host. It is the gate that has to be cleared before index.html becomes fully operational.

Source: cms/ui_assets/setup.html:1-100 — multi-step form and validation hooks.

5. Relationship Between the Two Surfaces

The agent-facing and operator-facing surfaces are not independent: they describe the same underlying CMS state from two angles. cms/mcp.py is what an LLM agent sees; cms/ui.py plus the four HTML pages is what a human sees while configuring, inspecting, and supervising that same agent fleet. The discovery layer is the union of both — every capability that an agent can call remotely is also visible, in some form, inside constellation.html or sentinel.html for the operator.

Source: cms/mcp.py:200-260 — capability definitions reused by the UI's agent graph. Source: cms/ui.py:220-280 — endpoints that the constellation view consumes to populate nodes. Source: cms/ui_assets/constellation.html:120-200 — client-side rendering of the agent graph. Source: cms/ui_assets/sentinel.html:120-200 — alert polling against the same backend.

For new contributors, the practical order of exploration is: read cms/mcp.py to learn the programmatic capability surface, then cms/ui.py to learn the HTTP surface, and finally the four HTML files in cms/ui_assets/ to learn how each capability is visualised.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Identity risk - Identity risk requires verification.

1. Identity risk: Identity risk requires verification

• Severity: medium
• Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | https://github.com/mrt150683-lgtm/atlas-cms

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/mrt150683-lgtm/atlas-cms

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/mrt150683-lgtm/atlas-cms

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/mrt150683-lgtm/atlas-cms

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/mrt150683-lgtm/atlas-cms

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/mrt150683-lgtm/atlas-cms

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/mrt150683-lgtm/atlas-cms

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using atlas-cms with real data or production workflows.

• Identity risk requires verification - GitHub / issue