# eimg/primer architecture

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

- Interactive diagram: https://gitdiagram.com/eimg/primer
- Repository: https://github.com/eimg/primer

## Overview

Primer turns registered organizational sources into permission-aware, ranked evidence and cited answers. The principal workflow is source registration and synchronization, canonical record processing and indexing, bounded query planning, hybrid retrieval with authorization and ranking, context construction, then answer generation and citation validation; traces and evaluations make decisions inspectable. CLI and React clients share the HTTP application and service layer. The graph preserves documented inspection, identity, connector, and evaluation capabilities; some unsampled implementation links rely on README statements rather than inspected source.

Main entry points: [`src/services.ts`](https://github.com/eimg/primer/blob/main/src/services.ts) (Application services), [`src/connectors/registry.ts`](https://github.com/eimg/primer/blob/main/src/connectors/registry.ts) (Connector registry), [`src/app.ts`](https://github.com/eimg/primer/blob/main/src/app.ts) (HTTP API), [`web/src/App.tsx`](https://github.com/eimg/primer/blob/main/web/src/App.tsx) (React application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_web["React application<br/>[App.tsx]"]
  node_webapi["Browser API client<br/>[api.ts]"]
  node_cli["CLI<br/>[cli.ts]"]
end

subgraph group_application["Application services"]
  node_http["HTTP API<br/>[app.ts]"]
  node_auth["Identity and access<br/>[auth.ts]"]
  node_services["Application services<br/>[services.ts]"]
  node_config["Runtime configuration<br/>[config.ts]"]
  node_webassets["Web assets<br/>[webAssets.ts]"]
end

subgraph group_ingestion["Source ingestion"]
  node_registry["Connector registry<br/>[registry.ts]"]
  node_connector["Connector providers<br/>[contracts.ts]"]
  node_slack["Slack export<br/>[slack-export.ts]"]
  node_markdown["Markdown processing<br/>[markdown.ts]"]
  node_processor["Canonical processor"]
  node_fixture["Acme fixture<br/>[fixture.ts]"]
end

subgraph group_knowledge["Retrieval and evidence"]
  node_database[("SQLite index<br/>[database.ts]")]
  node_planner["Query planning<br/>[planner.ts]"]
  node_embeddings["Embedding provider<br/>[embeddings.ts]"]
  node_ranking["Candidate ranking<br/>[ranking.ts]"]
  node_context["Authorized context<br/>[context.ts]"]
end

subgraph group_generation["Answers and evaluation"]
  node_answers["Answer generation<br/>[answers.ts]"]
  node_evaluation["Evaluation and traces<br/>[services.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -->|"requests"| node_webapi
node_webapi -->|"calls"| node_http
node_user -->|"runs"| node_cli
node_cli -->|"invokes"| node_services
node_http -->|"dispatches"| node_services
node_http -->|"authorizes"| node_auth
node_http -->|"serves"| node_webassets
node_services -->|"uses"| node_config
node_services -->|"synchronizes through"| node_registry
node_registry -->|"dispatches"| node_connector
node_registry -->|"loads provider"| node_slack
node_registry -->|"loads processor"| node_markdown
node_registry -->|"processes items"| node_processor
node_services -->|"persists and queries"| node_database
node_services -->|"validates and loads"| node_fixture
node_services -->|"plans queries"| node_planner
node_services -->|"embeds content"| node_embeddings
node_services -->|"ranks results"| node_ranking
node_services -->|"builds context"| node_context
node_services -->|"generates answers"| node_answers
node_services -->|"runs evaluations"| node_evaluation
node_services -->|"saves traces"| node_database
node_answers -->|"configures provider"| node_config
node_embeddings -->|"configures provider"| node_config
node_web -->|"inspects retrieval"| node_http

click node_web "https://github.com/eimg/primer/blob/main/web/src/App.tsx"
click node_webapi "https://github.com/eimg/primer/blob/main/web/src/api.ts"
click node_cli "https://github.com/eimg/primer/blob/main/src/cli.ts"
click node_http "https://github.com/eimg/primer/blob/main/src/app.ts"
click node_auth "https://github.com/eimg/primer/blob/main/src/auth.ts"
click node_services "https://github.com/eimg/primer/blob/main/src/services.ts"
click node_config "https://github.com/eimg/primer/blob/main/src/config.ts"
click node_registry "https://github.com/eimg/primer/blob/main/src/connectors/registry.ts"
click node_connector "https://github.com/eimg/primer/blob/main/src/connectors/contracts.ts"
click node_slack "https://github.com/eimg/primer/blob/main/src/connectors/slack-export.ts"
click node_markdown "https://github.com/eimg/primer/blob/main/src/markdown.ts"
click node_processor "https://github.com/eimg/primer/blob/main/src/connectors/canonical-processor.ts"
click node_database "https://github.com/eimg/primer/blob/main/src/database.ts"
click node_planner "https://github.com/eimg/primer/blob/main/src/planner.ts"
click node_embeddings "https://github.com/eimg/primer/blob/main/src/embeddings.ts"
click node_ranking "https://github.com/eimg/primer/blob/main/src/ranking.ts"
click node_context "https://github.com/eimg/primer/blob/main/src/context.ts"
click node_answers "https://github.com/eimg/primer/blob/main/src/answers.ts"
click node_evaluation "https://github.com/eimg/primer/blob/main/src/services.ts"
click node_fixture "https://github.com/eimg/primer/blob/main/src/fixture.ts"
click node_webassets "https://github.com/eimg/primer/blob/main/src/webAssets.ts"

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_web,node_webapi,node_cli,node_user toneBlue
class node_http,node_auth,node_services,node_config,node_webassets toneAmber
class node_registry,node_connector,node_slack,node_markdown,node_processor,node_fixture toneMint
class node_database,node_planner,node_embeddings,node_ranking,node_context toneRose
class node_answers,node_evaluation toneIndigo
```

## Components

### User interfaces

- [React application](https://github.com/eimg/primer/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Browser API client](https://github.com/eimg/primer/blob/main/web/src/api.ts): `web/src/api.ts`
- [CLI](https://github.com/eimg/primer/blob/main/src/cli.ts): `src/cli.ts`

### Application services

- [HTTP API](https://github.com/eimg/primer/blob/main/src/app.ts): `src/app.ts`
- [Identity and access](https://github.com/eimg/primer/blob/main/src/auth.ts): `src/auth.ts`
- [Application services](https://github.com/eimg/primer/blob/main/src/services.ts): `src/services.ts`
- [Runtime configuration](https://github.com/eimg/primer/blob/main/src/config.ts): `src/config.ts`
- [Web assets](https://github.com/eimg/primer/blob/main/src/webAssets.ts): `src/webAssets.ts`

### Source ingestion

- [Connector registry](https://github.com/eimg/primer/blob/main/src/connectors/registry.ts): `src/connectors/registry.ts`
- [Connector providers](https://github.com/eimg/primer/blob/main/src/connectors/contracts.ts): `src/connectors/contracts.ts`
- [Slack export](https://github.com/eimg/primer/blob/main/src/connectors/slack-export.ts): `src/connectors/slack-export.ts`
- [Markdown processing](https://github.com/eimg/primer/blob/main/src/markdown.ts): `src/markdown.ts`
- [Canonical processor](https://github.com/eimg/primer/blob/main/src/connectors/canonical-processor.ts): `src/connectors/canonical-processor.ts`
- [Acme fixture](https://github.com/eimg/primer/blob/main/src/fixture.ts): `src/fixture.ts`

### Retrieval and evidence

- [SQLite index](https://github.com/eimg/primer/blob/main/src/database.ts): `src/database.ts`
- [Query planning](https://github.com/eimg/primer/blob/main/src/planner.ts): `src/planner.ts`
- [Embedding provider](https://github.com/eimg/primer/blob/main/src/embeddings.ts): `src/embeddings.ts`
- [Candidate ranking](https://github.com/eimg/primer/blob/main/src/ranking.ts): `src/ranking.ts`
- [Authorized context](https://github.com/eimg/primer/blob/main/src/context.ts): `src/context.ts`

### Answers and evaluation

- [Answer generation](https://github.com/eimg/primer/blob/main/src/answers.ts): `src/answers.ts`
- [Evaluation and traces](https://github.com/eimg/primer/blob/main/src/services.ts): `src/services.ts`

### Other components

- **User**

## Connections

- User → React application: uses (evidence: `README.md`)
- React application → Browser API client: requests (evidence: `web/src/App.tsx`)
- Browser API client → HTTP API: calls (evidence: `README.md`)
- User → CLI: runs (evidence: `README.md`)
- CLI → Application services: invokes (evidence: `src/cli.ts`)
- HTTP API → Application services: dispatches (evidence: `src/app.ts`)
- HTTP API → Identity and access: authorizes (evidence: `src/app.ts`)
- HTTP API → Web assets: serves (evidence: `src/app.ts`)
- Application services → Runtime configuration: uses (evidence: `src/services.ts`)
- Application services → Connector registry: synchronizes through (evidence: `src/services.ts`)
- Connector registry → Connector providers: dispatches (evidence: `src/connectors/registry.ts`)
- Connector registry → Slack export: loads provider (evidence: `src/connectors/default.ts`)
- Connector registry → Markdown processing: loads processor (evidence: `src/connectors/default.ts`)
- Connector registry → Canonical processor: processes items (evidence: `src/connectors/default.ts`)
- Application services → SQLite index: persists and queries (evidence: `src/services.ts`)
- Application services → Acme fixture: validates and loads (evidence: `src/services.ts`)
- Application services → Query planning: plans queries (evidence: `src/services.ts`)
- Application services → Embedding provider: embeds content (evidence: `src/services.ts`)
- Application services → Candidate ranking: ranks results (evidence: `src/services.ts`)
- Application services → Authorized context: builds context (evidence: `src/services.ts`)
- Application services → Answer generation: generates answers (evidence: `src/services.ts`)
- Application services → Evaluation and traces: runs evaluations (evidence: `README.md`)
- Application services → SQLite index: saves traces (evidence: `README.md`)
- Answer generation → Runtime configuration: configures provider (evidence: `src/answers.ts`)
- Embedding provider → Runtime configuration: configures provider (evidence: `src/embeddings.ts`)
- React application → HTTP API: inspects retrieval (evidence: `README.md`)
