> ## 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 지식 플랫폼

> 채택한 오픈소스 Athena가 GitHub/OpenSpec의 engineering knowledge를 사람이 보고 Cursor와 ChatGPT가 검색할 수 있게 만드는 구조입니다.

# Athena 지식 플랫폼

Engineering System에서 말하는 **Athena는 우리가 검토하고 채택한 오픈소스 프로젝트 `jannismilz/athena`를 의미합니다.**

Athena가 모든 knowledge platform을 통칭하는 일반 명칭인 것은 아니고, Data Relay Labs가 기반 Athena 플랫폼을 새로 만든 것도 아닙니다. 우리는 이 오픈소스 프로젝트를 `xdr-labs/athena`로 fork해서 Engineering System 용도에 맞게 보강하고 있습니다.

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

Athena는 Engineering System의 **derived knowledge 및 retrieval platform**으로 사용합니다. GitHub, OpenSpec, code, test, ADR, release evidence는 계속 canonical source입니다.

## Athena는 Wiki.js가 아닙니다

Wiki.js는 Athena 안에 포함되는 구성요소 중 하나입니다.

```mermaid theme={null}
flowchart TB
    G["GitHub / OpenSpec<br/>Canonical Source"] --> S["Sync / Indexer"]
    S --> W["Wiki.js<br/>사람이 보는 페이지"]
    S --> E["Embedding Service"]
    E --> V["PostgreSQL + pgvector<br/>Semantic Index"]
    W --> V
    V --> M["Athena MCP Server"]
    M --> C["Cursor"]
    M --> H["ChatGPT / 기타 MCP Client"]
    W --> U["사람의 Browser"]
    D["Dashboard / Backup"] --> V
```

쉽게 말하면 **Athena가 우리가 채택한 전체 knowledge platform**이고, **Wiki.js는 그 안에서 사람이 보는 Wiki UI**입니다.

## 원래 Athena에 이미 있는 구성요소

아래 구성은 Engineering System을 위해 우리가 새로 만든 것이 아니라 upstream Athena에 원래 포함되어 있습니다.

| 구성요소                  | 역할                                            |
| --------------------- | --------------------------------------------- |
| Wiki.js               | 사람이 읽는 navigation과 knowledge page             |
| PostgreSQL + pgvector | Wiki 상태와 semantic vector search 저장            |
| Embedding service     | 문서와 질문을 semantic vector로 변환                   |
| Indexer               | Wiki content를 chunking/indexing해서 의미 기반 검색 준비 |
| MCP server            | AI client에 structured search/read 제공          |
| Dashboard             | content, indexing, activity, backup 상태 표시     |
| Backup service        | 복구를 위한 database/application backup 생성         |

## 우리 fork에서 추가한 부분

우리는 Athena를 Data Relay Engineering System에 맞추기 위해 다음을 추가했습니다.

* GitHub/OpenSpec → Athena synchronization 및 generated knowledge projection
* `projects/<project>/...` 구조와 project-scoped retrieval
* repository, ref, source path, Git blob까지 이어지는 provenance
* AI client용 read-only MCP hardening
* dependency 및 CI hardening

`RATIONALE_UNKNOWN`은 **upstream Athena의 내장 기능이나 fork에 hard-code된 기능이 아니라, POC에서 검증한 Engineering System 사용 규칙**입니다. AI client에게 canonical material에 WHY가 없으면 추측하지 말고 이 상태를 명시하도록 지시합니다.

이 기능을 추가해도 authority는 바뀌지 않습니다. GitHub/OpenSpec이 canonical이고 Athena는 derived layer입니다.

## 현재 POC에서 이미 실제 동작한 것

아래 구성은 계획만 세운 것이 아닙니다. `dev-dp-mirror` POC 서버에서 이미 실제로 실행하고 검증했습니다.

| 구성요소                  | POC 상태                                         |
| --------------------- | ---------------------------------------------- |
| Wiki.js               | 실행 완료, generated knowledge page 직접 확인          |
| PostgreSQL + pgvector | 실행 완료, semantic-search chunk 저장                |
| Embedding service     | multilingual embedding으로 실제 검색 성공              |
| Indexer               | current spec + archived decision history 색인 완료 |
| MCP server            | Cursor에서 실제 연결 및 검색 성공                         |
| Dashboard             | index/activity/backup 상태 조회 확인                 |
| Backup                | backup 생성뿐 아니라 별도 DB restore까지 검증              |

다만 이것은 **POC 서버에 적용된 상태**입니다. 정식 OVHcloud 서버는 아직 provisioning 중이며, 위 stack은 아직 production 서버로 이전하지 않았습니다.

## Source of Truth 규칙

Athena는 의도적으로 derived layer입니다.

```text theme={null}
GitHub / OpenSpec / Code / Tests / ADR
              ↓
            Athena
              ↓
         검색 / 설명 / 회상
```

Athena와 canonical Git 내용이 충돌하면 **항상 Git이 우선**합니다.

자동 생성된 project page를 authoritative product spec처럼 직접 수정해서는 안 됩니다.

## POC에서 확인한 것

Data Relay Link POC에서는 Engineering System에 필요한 핵심 흐름을 실제로 검증했습니다.

* Cursor가 MCP를 통해 Athena에 연결됨
* 한국어와 영어 질문 모두 semantic search 가능
* 현재 계약과 과거 design rationale을 구분해 검색 가능
* Cursor가 Wiki path와 원본 OpenSpec source path를 함께 반환 가능
* canonical material에 WHY가 없으면 이유를 만들어내지 않고 `RATIONALE_UNKNOWN`으로 응답
* current spec과 archived decision history를 함께 색인하면서도 Athena가 source of truth가 되지 않음

이 결과를 바탕으로 cross-project searchable knowledge layer를 Tela에서 Athena로 전환합니다.

## Production 배포 target

현재 production target은 **OVHcloud Singapore VPS**입니다.

선택한 baseline:

| 항목                | Target                                                         |
| ----------------- | -------------------------------------------------------------- |
| Provider / Region | OVHcloud / Singapore                                           |
| OS                | Ubuntu 24.04 LTS                                               |
| Compute           | 4 vCore                                                        |
| Memory            | 8 GB RAM                                                       |
| Storage           | 75 GB NVMe                                                     |
| Backup            | Provider automatic backup + Athena application/database backup |
| 외부 노출             | Reverse proxy를 통한 HTTPS만 공개, 내부 service는 직접 노출하지 않음            |

OVHcloud는 현재 선택한 운영 인프라일 뿐 Engineering System의 normative contract는 아닙니다. 나중에 provider를 바꾸더라도 Athena의 역할과 GitHub의 authority는 그대로 유지됩니다.

## 목표 운영 흐름

```mermaid theme={null}
flowchart LR
    A["Repository 변경"] --> B["GitHub/OpenSpec"]
    B --> C["Athena 자동 Sync"]
    C --> D["Index / Embedding"]
    D --> E["Cursor / ChatGPT 검색"]
    E --> F["근거와 함께 답변"]
```

최종 목표는 **Wiki를 사람이 수동으로 관리하지 않는 것**입니다. 사람과 AI는 canonical repository artifact를 관리하고, Athena가 선택된 durable knowledge를 자동으로 동기화하고 색인합니다.

정식 Athena 서버가 준비되기 전까지는 이 transition knowledge가 chat에만 남지 않도록 Tela에 임시로 기록할 수 있습니다.