# nicolas-systems/nicolas architecture

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

- Interactive diagram: https://gitdiagram.com/nicolas-systems/nicolas
- Repository: https://github.com/nicolas-systems/nicolas

## Overview

Nicolas is a tenant-aware evidence-gating product: users submit questions, and the runtime normalizes them, retrieves evidence, compiles facts, resolves claim support, enforces abstention, and returns a DecisionPacket. Separate branches handle document ingestion/connectors, admin and API-key security, and evaluation. Edges reflect calls visible in excerpts or relationships stated in the README; several services and API routes are indexed but unsampled, so their internal links are omitted.

Main entry points: [`nicolas_product/runtime.py`](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/runtime.py) (Runtime Orchestrator), [`nicolas_product/api.py`](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/api.py) (HTTP API), [`nicolas_product/repositories.py`](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/repositories.py) (Tenant Repository), [`nicolas_product/services/ingestion.py`](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/ingestion.py) (Ingestion Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["API & Security"]
  node_api["HTTP API<br/>[api.py]"]
  node_auth["Tenant Auth<br/>[security.py]"]
end

subgraph group_ingestion["Source Ingestion"]
  node_ingestion["Ingestion Service<br/>[ingestion.py]"]
  node_connectors["Source Connectors<br/>[connectors.py]"]
  node_parser["Document Parsing<br/>[parsing.py]"]
end

subgraph group_runtime["Evidence Runtime"]
  node_schemas["Product Schemas<br/>[schemas.py]"]
  node_runtime["Runtime Orchestrator<br/>[runtime.py]"]
  node_normalize["Query Normalization<br/>[normalization.py]"]
  node_retrieve["Evidence Retrieval<br/>[retrieval.py]"]
  node_vectors["Vector Search<br/>[vector_index.py]"]
  node_compile["Fact Compilation<br/>[fact_compiler.py]"]
  node_decision["Claim Decisions<br/>[decision_engine.py]"]
  node_enforce["Answer Enforcement<br/>[answer_enforcer.py]"]
  node_baseline["Baseline RAG<br/>[baseline_rag.py]"]
  node_repository[("Tenant Repository<br/>[repositories.py]")]
end

subgraph group_operations["Admin &amp; Evaluation"]
  node_admin["Admin Services<br/>[admin.py]"]
  node_evaluation["Evaluation Runner<br/>[evaluation.py]"]
end

node_user(("Questioner"))
node_external_sources(("Content Sources"))
node_client(("API Client"))

node_client -->|"calls"| node_api
node_api -->|"routes queries"| node_runtime
node_api -->|"checks keys"| node_auth
node_runtime -->|"normalizes"| node_normalize
node_runtime -->|"retrieves evidence"| node_retrieve
node_runtime -->|"compiles facts"| node_compile
node_runtime -->|"solves claims"| node_decision
node_runtime -->|"enforces answers"| node_enforce
node_runtime -->|"reads and writes"| node_repository
node_retrieve -->|"loads documents"| node_repository
node_retrieve -->|"searches"| node_vectors
node_vectors -->|"loads vectors"| node_repository
node_baseline -->|"retrieves evidence"| node_retrieve
node_ingestion -->|"fetches documents"| node_connectors
node_ingestion -->|"parses files"| node_parser
node_ingestion -->|"stores documents"| node_repository
node_ingestion -->|"indexes documents"| node_vectors
node_external_sources -.->|"provides content"| node_connectors
node_api -->|"routes ingestion"| node_ingestion
node_api -->|"routes admin"| node_admin
node_api -->|"routes evaluation"| node_evaluation
node_admin -->|"manages records"| node_repository
node_evaluation -->|"loads cases"| node_repository
node_evaluation -->|"compares baseline"| node_baseline
node_runtime -->|"exchanges packets"| node_schemas

click node_api "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/api.py"
click node_auth "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/security.py"
click node_schemas "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/schemas.py"
click node_runtime "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/runtime.py"
click node_normalize "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/normalization.py"
click node_retrieve "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/retrieval.py"
click node_vectors "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/vector_index.py"
click node_compile "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/fact_compiler.py"
click node_decision "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/decision_engine.py"
click node_enforce "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/answer_enforcer.py"
click node_baseline "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/baseline_rag.py"
click node_repository "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/repositories.py"
click node_ingestion "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/ingestion.py"
click node_connectors "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/connectors.py"
click node_parser "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/parsing.py"
click node_admin "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/admin.py"
click node_evaluation "https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/evaluation.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_auth,node_client toneBlue
class node_ingestion,node_connectors,node_parser toneAmber
class node_schemas,node_runtime,node_normalize,node_retrieve,node_vectors,node_compile,node_decision,node_enforce,node_baseline,node_repository toneMint
class node_admin,node_evaluation toneRose
class node_user,node_external_sources toneIndigo
```

## Components

### API & Security

- [HTTP API](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/api.py): `nicolas_product/api.py`
- [Tenant Auth](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/security.py): `nicolas_product/security.py`

### Source Ingestion

- [Ingestion Service](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/ingestion.py): `nicolas_product/services/ingestion.py`
- [Source Connectors](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/connectors.py): `nicolas_product/connectors.py`
- [Document Parsing](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/parsing.py): `nicolas_product/parsing.py`

### Evidence Runtime

- [Product Schemas](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/schemas.py): `nicolas_product/schemas.py`
- [Runtime Orchestrator](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/runtime.py): `nicolas_product/runtime.py`
- [Query Normalization](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/normalization.py): `nicolas_product/services/normalization.py`
- [Evidence Retrieval](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/retrieval.py): `nicolas_product/services/retrieval.py`
- [Vector Search](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/vector_index.py): `nicolas_product/services/vector_index.py`
- [Fact Compilation](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/fact_compiler.py): `nicolas_product/services/fact_compiler.py`
- [Claim Decisions](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/decision_engine.py): `nicolas_product/services/decision_engine.py`
- [Answer Enforcement](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/answer_enforcer.py): `nicolas_product/services/answer_enforcer.py`
- [Baseline RAG](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/baseline_rag.py): `nicolas_product/services/baseline_rag.py`
- [Tenant Repository](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/repositories.py): `nicolas_product/repositories.py`

### Admin & Evaluation

- [Admin Services](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/admin.py): `nicolas_product/services/admin.py`
- [Evaluation Runner](https://github.com/nicolas-systems/nicolas/blob/main/nicolas_product/services/evaluation.py): `nicolas_product/services/evaluation.py`

### Other components

- **Questioner**
- **Content Sources**
- **API Client**

## Connections

- API Client → HTTP API: calls (evidence: `README.md`)
- HTTP API → Runtime Orchestrator: routes queries (evidence: `nicolas_product/api.py`)
- HTTP API → Tenant Auth: checks keys (evidence: `README.md`)
- Runtime Orchestrator → Query Normalization: normalizes (evidence: `nicolas_product/runtime.py`)
- Runtime Orchestrator → Evidence Retrieval: retrieves evidence (evidence: `nicolas_product/runtime.py`)
- Runtime Orchestrator → Fact Compilation: compiles facts (evidence: `nicolas_product/runtime.py`)
- Runtime Orchestrator → Claim Decisions: solves claims (evidence: `nicolas_product/runtime.py`)
- Runtime Orchestrator → Answer Enforcement: enforces answers (evidence: `README.md`)
- Runtime Orchestrator → Tenant Repository: reads and writes (evidence: `nicolas_product/runtime.py`)
- Evidence Retrieval → Tenant Repository: loads documents (evidence: `nicolas_product/services/retrieval.py`)
- Evidence Retrieval → Vector Search: searches (evidence: `nicolas_product/services/retrieval.py`)
- Vector Search → Tenant Repository: loads vectors (evidence: `nicolas_product/services/vector_index.py`)
- Baseline RAG → Evidence Retrieval: retrieves evidence (evidence: `nicolas_product/services/baseline_rag.py`)
- Ingestion Service → Source Connectors: fetches documents (evidence: `nicolas_product/services/ingestion.py`)
- Ingestion Service → Document Parsing: parses files (evidence: `nicolas_product/services/ingestion.py`)
- Ingestion Service → Tenant Repository: stores documents (evidence: `nicolas_product/services/ingestion.py`)
- Ingestion Service → Vector Search: indexes documents (evidence: `nicolas_product/services/ingestion.py`)
- Content Sources → Source Connectors: provides content (evidence: `README.md`)
- HTTP API → Ingestion Service: routes ingestion (evidence: `README.md`)
- HTTP API → Admin Services: routes admin (evidence: `README.md`)
- HTTP API → Evaluation Runner: routes evaluation (evidence: `README.md`)
- Admin Services → Tenant Repository: manages records (evidence: `nicolas_product/services/admin.py`)
- Evaluation Runner → Tenant Repository: loads cases (evidence: `nicolas_product/services/evaluation.py`)
- Evaluation Runner → Baseline RAG: compares baseline (evidence: `nicolas_product/services/evaluation.py`)
- Runtime Orchestrator → Product Schemas: exchanges packets (evidence: `nicolas_product/runtime.py`)