# naknakgeo/engineeringrag architecture

> Architecture diagram of the GitHub repository naknakgeo/engineeringrag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/naknakgeo/engineeringrag
- Repository: https://github.com/naknakgeo/engineeringrag

## Overview

Engineering Intelligence OS is currently a Phase 0 foundation: local services, PostgreSQL-backed infrastructure, project-indexing and knowledge primitives, and observability. The principal visible workflow is a client calling the API, which routes requests to product capabilities; project sync can be queued and processed by a worker, while knowledge evidence follows a staged trust pipeline. The README describes broader retrieval, routing, policy, and workflow ambitions, but explicitly says Phase 1+ does not yet exist. Several connections below are limited to documented wiring or sampled imports; unsampled behavior is not inferred.

Main entry points: [`packages/storage/src/eios_storage/engine.py`](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/storage/src/eios_storage/engine.py) (Engineering OS PostgreSQL), [`apps/api/src/eios_api/app.py`](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/apps/api/src/eios_api/app.py) (HTTP API), [`packages/project_intelligence/src/eios_project_intelligence/service.py`](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/project_intelligence/src/eios_project_intelligence/service.py) (Project Service), [`packages/runtime/src/eios_runtime/container.py`](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/runtime/src/eios_runtime/container.py) (Runtime Container)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_services["Service Entry Points"]
  node_api["HTTP API<br/>[app.py]"]
  node_api_routes["API Routes"]
  node_mcp["MCP Server<br/>[server.py]"]
  node_worker["Worker<br/>[worker.py]"]
end

subgraph group_project["Project Intelligence"]
  node_project_service["Project Service<br/>[service.py]"]
  node_project_indexer["Project Indexer<br/>[indexer.py]"]
  node_project_store[("Project Store<br/>[store.py]")]
  node_parsers["Language Parsers"]
end

subgraph group_knowledge["Knowledge Pipeline"]
  node_knowledge_pipeline["Evidence Pipeline<br/>[pipeline.py]"]
  node_knowledge_service["Knowledge Service<br/>[service.py]"]
  node_knowledge_repos["Knowledge Repositories"]
  node_blob_store["Evidence Blobs<br/>[blob_store.py]"]
end

subgraph group_operations["Jobs and Observability"]
  node_job_queue[("Job Queue<br/>[queue.py]")]
  node_job_runner["Job Runner<br/>[runner.py]"]
  node_recorder["Run Recorder<br/>[recorder.py]"]
  node_event_store[("Event and Run Store<br/>[postgres.py]")]
end

subgraph group_foundation["Shared Foundation"]
  node_container["Runtime Container<br/>[container.py]"]
  node_postgres[("Engineering OS PostgreSQL<br/>[engine.py]")]
  node_settings["Runtime Settings<br/>[settings.py]"]
  node_domain_contracts["Domain Contracts"]
  node_logging["Structured Logging<br/>[logging.py]"]
end

node_client(("API Client"))

node_client -->|"sends requests"| node_api
node_api -->|"registers routes"| node_api_routes
node_api -->|"builds runtime"| node_container
node_api -->|"builds engine"| node_postgres
node_api -->|"reads settings"| node_settings
node_mcp -.->|"uses storage"| node_postgres
node_worker -->|"runs jobs"| node_job_runner
node_worker -.->|"builds engine"| node_postgres
node_worker -.->|"configures logs"| node_logging
node_container -.->|"wires knowledge"| node_knowledge_service
node_container -.->|"wires project intelligence"| node_project_service
node_container -.->|"wires jobs"| node_job_queue
node_api_routes -->|"accesses project data"| node_project_store
node_project_service -->|"syncs project"| node_project_indexer
node_project_service -->|"reads project data"| node_project_store
node_project_service -->|"queues sync"| node_job_queue
node_project_service -->|"records runs"| node_recorder
node_project_indexer -.->|"parses source"| node_parsers
node_knowledge_pipeline -->|"stores evidence"| node_blob_store
node_knowledge_pipeline -->|"promotes findings"| node_knowledge_service
node_knowledge_service -->|"persists knowledge"| node_knowledge_repos
node_knowledge_service -->|"uses domain types"| node_domain_contracts
node_job_runner -->|"claims jobs"| node_job_queue
node_recorder -->|"persists runs"| node_event_store
node_event_store -->|"stores events"| node_postgres
node_job_queue -->|"stores jobs"| node_postgres
node_settings -->|"restricts database"| node_postgres

click node_api "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/apps/api/src/eios_api/app.py"
click node_api_routes "https://github.com/naknakgeo/engineeringrag/tree/claude/exciting-tesla-16phur/apps/api/src/eios_api/routes"
click node_mcp "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/apps/mcp_server/src/eios_mcp/server.py"
click node_worker "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/apps/worker/src/eios_worker/worker.py"
click node_container "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/runtime/src/eios_runtime/container.py"
click node_project_service "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/project_intelligence/src/eios_project_intelligence/service.py"
click node_project_indexer "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/project_intelligence/src/eios_project_intelligence/indexer.py"
click node_project_store "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/project_intelligence/src/eios_project_intelligence/store.py"
click node_parsers "https://github.com/naknakgeo/engineeringrag/tree/claude/exciting-tesla-16phur/packages/project_intelligence/src/eios_project_intelligence/parsers"
click node_knowledge_pipeline "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/knowledge/src/eios_knowledge/pipeline.py"
click node_knowledge_service "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/knowledge/src/eios_knowledge/service.py"
click node_knowledge_repos "https://github.com/naknakgeo/engineeringrag/tree/claude/exciting-tesla-16phur/packages/knowledge/src/eios_knowledge"
click node_blob_store "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/knowledge/src/eios_knowledge/blob_store.py"
click node_job_queue "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/jobs/src/eios_jobs/queue.py"
click node_job_runner "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/jobs/src/eios_jobs/runner.py"
click node_recorder "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/observability/src/eios_observability/recorder.py"
click node_event_store "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/observability/src/eios_observability/postgres.py"
click node_postgres "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/storage/src/eios_storage/engine.py"
click node_settings "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/core/src/eios_core/settings.py"
click node_domain_contracts "https://github.com/naknakgeo/engineeringrag/tree/claude/exciting-tesla-16phur/packages/domain/src/eios_domain"
click node_logging "https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/core/src/eios_core/logging.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_api_routes,node_mcp,node_worker,node_client toneBlue
class node_project_service,node_project_indexer,node_project_store,node_parsers toneAmber
class node_knowledge_pipeline,node_knowledge_service,node_knowledge_repos,node_blob_store toneMint
class node_job_queue,node_job_runner,node_recorder,node_event_store toneRose
class node_container,node_postgres,node_settings,node_domain_contracts,node_logging toneIndigo
```

## Components

### Service Entry Points

- [HTTP API](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/apps/api/src/eios_api/app.py): `apps/api/src/eios_api/app.py`
- [API Routes](https://github.com/naknakgeo/engineeringrag/tree/claude/exciting-tesla-16phur/apps/api/src/eios_api/routes): `apps/api/src/eios_api/routes`
- [MCP Server](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/apps/mcp_server/src/eios_mcp/server.py): `apps/mcp_server/src/eios_mcp/server.py`
- [Worker](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/apps/worker/src/eios_worker/worker.py): `apps/worker/src/eios_worker/worker.py`

### Project Intelligence

- [Project Service](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/project_intelligence/src/eios_project_intelligence/service.py): `packages/project_intelligence/src/eios_project_intelligence/service.py`
- [Project Indexer](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/project_intelligence/src/eios_project_intelligence/indexer.py): `packages/project_intelligence/src/eios_project_intelligence/indexer.py`
- [Project Store](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/project_intelligence/src/eios_project_intelligence/store.py): `packages/project_intelligence/src/eios_project_intelligence/store.py`
- [Language Parsers](https://github.com/naknakgeo/engineeringrag/tree/claude/exciting-tesla-16phur/packages/project_intelligence/src/eios_project_intelligence/parsers): `packages/project_intelligence/src/eios_project_intelligence/parsers`

### Knowledge Pipeline

- [Evidence Pipeline](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/knowledge/src/eios_knowledge/pipeline.py): `packages/knowledge/src/eios_knowledge/pipeline.py`
- [Knowledge Service](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/knowledge/src/eios_knowledge/service.py): `packages/knowledge/src/eios_knowledge/service.py`
- [Knowledge Repositories](https://github.com/naknakgeo/engineeringrag/tree/claude/exciting-tesla-16phur/packages/knowledge/src/eios_knowledge): `packages/knowledge/src/eios_knowledge`
- [Evidence Blobs](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/knowledge/src/eios_knowledge/blob_store.py): `packages/knowledge/src/eios_knowledge/blob_store.py`

### Jobs and Observability

- [Job Queue](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/jobs/src/eios_jobs/queue.py): `packages/jobs/src/eios_jobs/queue.py`
- [Job Runner](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/jobs/src/eios_jobs/runner.py): `packages/jobs/src/eios_jobs/runner.py`
- [Run Recorder](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/observability/src/eios_observability/recorder.py): `packages/observability/src/eios_observability/recorder.py`
- [Event and Run Store](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/observability/src/eios_observability/postgres.py): `packages/observability/src/eios_observability/postgres.py`

### Shared Foundation

- [Runtime Container](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/runtime/src/eios_runtime/container.py): `packages/runtime/src/eios_runtime/container.py`
- [Engineering OS PostgreSQL](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/storage/src/eios_storage/engine.py): `packages/storage/src/eios_storage/engine.py`
- [Runtime Settings](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/core/src/eios_core/settings.py): `packages/core/src/eios_core/settings.py`
- [Domain Contracts](https://github.com/naknakgeo/engineeringrag/tree/claude/exciting-tesla-16phur/packages/domain/src/eios_domain): `packages/domain/src/eios_domain`
- [Structured Logging](https://github.com/naknakgeo/engineeringrag/blob/claude/exciting-tesla-16phur/packages/core/src/eios_core/logging.py): `packages/core/src/eios_core/logging.py`

### Other components

- **API Client**

## Connections

- API Client → HTTP API: sends requests (evidence: `README.md`)
- HTTP API → API Routes: registers routes (evidence: `apps/api/src/eios_api/app.py`)
- HTTP API → Runtime Container: builds runtime (evidence: `apps/api/src/eios_api/app.py`)
- HTTP API → Engineering OS PostgreSQL: builds engine (evidence: `apps/api/src/eios_api/app.py`)
- HTTP API → Runtime Settings: reads settings (evidence: `apps/api/src/eios_api/app.py`)
- MCP Server → Engineering OS PostgreSQL: uses storage (evidence: `apps/mcp_server/src/eios_mcp/server.py`)
- Worker → Job Runner: runs jobs (evidence: `apps/worker/src/eios_worker/worker.py`)
- Worker → Engineering OS PostgreSQL: builds engine (evidence: `apps/worker/src/eios_worker/worker.py`)
- Worker → Structured Logging: configures logs (evidence: `apps/worker/src/eios_worker/worker.py`)
- Runtime Container → Knowledge Service: wires knowledge (evidence: `packages/runtime/src/eios_runtime/container.py`)
- Runtime Container → Project Service: wires project intelligence (evidence: `packages/runtime/src/eios_runtime/container.py`)
- Runtime Container → Job Queue: wires jobs (evidence: `packages/runtime/src/eios_runtime/container.py`)
- API Routes → Project Store: accesses project data (evidence: `apps/api/src/eios_api/routes/projects.py`)
- Project Service → Project Indexer: syncs project (evidence: `packages/project_intelligence/src/eios_project_intelligence/service.py`)
- Project Service → Project Store: reads project data (evidence: `packages/project_intelligence/src/eios_project_intelligence/service.py`)
- Project Service → Job Queue: queues sync (evidence: `packages/project_intelligence/src/eios_project_intelligence/service.py`)
- Project Service → Run Recorder: records runs (evidence: `packages/project_intelligence/src/eios_project_intelligence/service.py`)
- Project Indexer → Language Parsers: parses source
- Evidence Pipeline → Evidence Blobs: stores evidence (evidence: `packages/knowledge/src/eios_knowledge/pipeline.py`)
- Evidence Pipeline → Knowledge Service: promotes findings (evidence: `packages/knowledge/src/eios_knowledge/pipeline.py`)
- Knowledge Service → Knowledge Repositories: persists knowledge (evidence: `packages/knowledge/src/eios_knowledge/service.py`)
- Knowledge Service → Domain Contracts: uses domain types (evidence: `packages/knowledge/src/eios_knowledge/service.py`)
- Job Runner → Job Queue: claims jobs (evidence: `packages/jobs/src/eios_jobs/runner.py`)
- Run Recorder → Event and Run Store: persists runs (evidence: `packages/observability/src/eios_observability/recorder.py`)
- Event and Run Store → Engineering OS PostgreSQL: stores events (evidence: `packages/observability/src/eios_observability/postgres.py`)
- Job Queue → Engineering OS PostgreSQL: stores jobs (evidence: `packages/jobs/src/eios_jobs/queue.py`)
- Runtime Settings → Engineering OS PostgreSQL: restricts database (evidence: `packages/core/src/eios_core/settings.py`)
