> ## 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.

# Athena Knowledge Platform

> How the adopted open-source Athena project turns GitHub/OpenSpec engineering knowledge into searchable context for humans, Cursor, and ChatGPT.

# Athena Knowledge Platform

In this Engineering System, **Athena means the open-source project `jannismilz/athena` that we evaluated and adopted**.

It is **not** a generic industry name for all knowledge platforms, and Data Relay Labs did not create the base Athena platform. We maintain a fork at `xdr-labs/athena` so we can adapt the upstream project to our Engineering System.

* Upstream: [https://github.com/jannismilz/athena](https://github.com/jannismilz/athena)
* Our fork: [https://github.com/xdr-labs/athena](https://github.com/xdr-labs/athena)

Athena is used as the Engineering System's **derived knowledge and retrieval platform**. GitHub, OpenSpec, code, tests, ADRs, and release evidence remain canonical.

## Athena is not Wiki.js

Wiki.js is only one component inside Athena.

```mermaid theme={null}
flowchart TB
    G["GitHub / OpenSpec<br/>Canonical Source"] --> S["Sync / Indexer"]
    S --> W["Wiki.js<br/>Human-readable pages"]
    S --> E["Embedding Service"]
    E --> V["PostgreSQL + pgvector<br/>Semantic index"]
    W --> V
    V --> M["Athena MCP Server"]
    M --> C["Cursor"]
    M --> H["ChatGPT / other MCP clients"]
    W --> U["Human browser"]
    D["Dashboard / Backup"] --> V
```

Think of **Athena as the whole adopted knowledge platform** and **Wiki.js as its human-facing wiki UI**.

## What comes from upstream Athena

The following are already part of the upstream Athena architecture; they were not invented for this Engineering System.

| Component             | Role                                                   |
| --------------------- | ------------------------------------------------------ |
| Wiki.js               | Human-readable navigation and pages                    |
| PostgreSQL + pgvector | Wiki state plus vector-search storage                  |
| Embedding service     | Converts content and questions into semantic vectors   |
| Indexer               | Chunks and indexes Wiki content for semantic retrieval |
| MCP server            | Gives AI clients structured search/read access         |
| Dashboard             | Shows content, indexing, activity, and backup status   |
| Backup service        | Creates database/application backups for recovery      |

## What our fork adds

Our fork adapts Athena to the Data Relay Engineering System.

* GitHub/OpenSpec → Athena synchronization and generated knowledge projections
* `projects/<project>/...` organization and project-scoped retrieval
* provenance back to repository, ref, source path, and Git blob
* safer read-only MCP use for AI clients
* dependency and CI hardening for our operating model

`RATIONALE_UNKNOWN` is an **Engineering System usage rule validated in the POC prompts**, not a built-in upstream Athena feature or a hard-coded fork capability. AI clients are instructed to use it when the indexed canonical material does not contain the requested rationale.

These additions do not change the authority model: GitHub/OpenSpec remains canonical and Athena remains derived.

## What is already running in the POC

These components are not merely planned. They were already started and exercised on the `dev-dp-mirror` POC host.

| Component             | POC state                                               |
| --------------------- | ------------------------------------------------------- |
| Wiki.js               | Running and used to view generated knowledge pages      |
| PostgreSQL + pgvector | Running and storing semantic-search chunks              |
| Embedding service     | Running with multilingual embeddings                    |
| Indexer               | Running and indexing current specs + archived decisions |
| MCP server            | Connected successfully from Cursor                      |
| Dashboard             | Running and reporting index/activity/backup state       |
| Backup                | Backup and isolated restore were both validated         |

The POC is temporary. The production server is still being provisioned and the above stack has **not yet been migrated to the final OVHcloud host**.

## Source-of-truth rule

Athena is intentionally derived.

```text theme={null}
GitHub / OpenSpec / Code / Tests / ADR
              ↓
            Athena
              ↓
      Search / explanation / recall
```

If Athena disagrees with canonical Git content, **Git content wins**.

Generated project pages should not be edited as if they were authoritative product specifications.

## What the POC proved

The Data Relay Link POC validated the workflows that matter most for this Engineering System:

* Cursor can connect to Athena through MCP.
* Semantic search works for Korean and English questions.
* Athena can retrieve a design rationale separately from the current contract.
* Cursor can return Wiki paths and original OpenSpec source paths.
* When rationale is not present in the indexed canonical material, the expected behavior is to return `RATIONALE_UNKNOWN` rather than invent an explanation.
* Current specs and archived decision history can be indexed together without making Athena the source of truth.

This is the basis for replacing Tela as the cross-project searchable knowledge layer.

## Production deployment target

The current production target is an **OVHcloud Singapore VPS**.

Selected baseline:

| Item              | Target                                                                         |
| ----------------- | ------------------------------------------------------------------------------ |
| Provider / region | OVHcloud / Singapore                                                           |
| OS                | Ubuntu 24.04 LTS                                                               |
| Compute           | 4 vCore                                                                        |
| Memory            | 8 GB RAM                                                                       |
| Storage           | 75 GB NVMe                                                                     |
| Backup            | Provider automated backup + Athena application/database backup                 |
| Exposure          | HTTPS only through a reverse proxy; internal services are not exposed directly |

The hosting provider is an operational choice, not part of the normative Engineering System contract. A future migration to another provider should not change Athena's role or GitHub's authority.

## Intended operating flow

```mermaid theme={null}
flowchart LR
    A["Repository change"] --> B["GitHub/OpenSpec"]
    B --> C["Automated Athena sync"]
    C --> D["Index / embeddings"]
    D --> E["Cursor / ChatGPT search"]
    E --> F["Answer with provenance"]
```

The target end state is **no manual Wiki maintenance**. Humans and AI maintain canonical repository artifacts; Athena synchronizes and indexes the selected durable knowledge automatically.

Until the production Athena server is ready, Tela may temporarily hold transition notes so this knowledge does not exist only in chat.