> ## Documentation Index
> Fetch the complete documentation index at: https://engineering.datarelay.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How ChatGPT, Cursor, GitHub, Desktop Commander, Athena, tests, and release evidence fit together.

# System architecture

The system deliberately gives each tool one primary job instead of asking one AI tool to do everything.

## System layers

```mermaid theme={null}
flowchart TB
    H["Human Layer<br/>engineering.datarelay.run"]
    K["Knowledge Layer<br/>Athena"]
    C["Coordination Layer<br/>AI Work Packet"]
    N["Normative Layer<br/>GitHub Code · Spec · Test · CI"]
    X["Execution Layer<br/>Cursor · Dev Server · Runtime"]

    H --> N
    K --> N
    C --> N
    X --> N
    N --> X
```

The handbook and Athena help people understand and retrieve context. GitHub and executed evidence remain authoritative for current product and release state.

## Responsibility map

| Component                    | Primary responsibility                                                                   | Not the source of truth for                     |
| ---------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------- |
| Owner                        | Product requirements, scope, final decisions, release approval, human UX judgment        | Implementation detail unless explicitly decided |
| ChatGPT                      | Requirements analysis, architecture, design, documentation, review, next-action planning | Current Git state                               |
| Cursor                       | Repository implementation, affected tests, local evidence                                | Long-term product decisions                     |
| Automation / CI              | Deterministic validation, security/performance gates, artifact verification              | Product intent                                  |
| GitHub                       | Code, history, PRs, CI, specs, Work Packets, release evidence                            | Human-friendly narrative                        |
| Desktop Commander Remote MCP | Direct audit of authorized development hosts                                             | Durable project history                         |
| Athena                       | Searchable decision/history layer                                                        | Runtime truth or release evidence               |
| Engineering System           | Common engineering and AI workflow standard                                              | Product-specific behavior                       |
| Engineering System Docs      | Human-readable handbook                                                                  | Normative engineering rules                     |

## Authority order

When information conflicts, use this order:

1. actual code, config, schema, runtime, and immutable Git state
2. canonical product/specification artifacts
3. repository engineering metadata
4. executed deterministic test and CI evidence
5. AI Work Packet current coordination state
6. Athena / derived documentation
7. conversation history

This order prevents a stale chat, roadmap, or wiki page from silently overriding the current product.

```mermaid theme={null}
flowchart TD
    A["1. Code / Config / Schema / Runtime / Git"] --> B["2. Canonical Product Spec"]
    B --> C["3. Repository Engineering Metadata"]
    C --> D["4. Executed Test / CI Evidence"]
    D --> E["5. AI Work Packet"]
    E --> F["6. Athena / Derived Docs"]
    F --> G["7. Conversation History"]
```

## Two repositories, two purposes

**datarelay-labs/engineering-system**

Canonical and machine-consumed. It contains standards, adapters, templates, validation logic, /resume, and session-continuity rules.

**datarelay-labs/engineering-system-docs**

Human-readable. It explains why the system exists, how the pieces fit together, how to adopt it, and what problems were solved.

<Warning>
  If this site disagrees with the canonical Engineering System repository, the canonical repository wins.
</Warning>

## Project-local adoption

Base Engineering System adoption requires the small repository entrypoint used by agents and CI:

```text theme={null}
AGENTS.md
.engineering/project.yaml
.engineering/tests.yaml
.engineering/release.yaml
```

Session-continuity files such as `.cursor/commands/resume.md` and the AI Work Packet Issue template are added when that workflow is used.

The repository should not copy every Engineering System standard into itself. It should pin and reference the canonical system.