# adityakumar0009/soverign-ai architecture

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

- Interactive diagram: https://gitdiagram.com/adityakumar0009/soverign-ai
- Repository: https://github.com/adityakumar0009/soverign-ai

## Overview

This repository appears to implement a document-ingestion API. The intended user journey is to submit a file, select a parser, process and normalize its content, validate it, and represent the result with document and related schemas. The tree also signals support for PDF, DOCX, Excel, images, PowerPoint, and text; most format-specific modules were not sampled, so their runtime connections are uncertain. The README is empty, and the shown excerpts do not establish the complete upload-to-processing call chain; uncertain links are marked dashed without evidence.

Main entry points: [`app/ingestion/registry.py`](https://github.com/adityakumar0009/soverign-ai/blob/main/app/ingestion/registry.py) (Parser Registry), [`app/ingestion/orchestrator.py`](https://github.com/adityakumar0009/soverign-ai/blob/main/app/ingestion/orchestrator.py) (Ingestion Orchestrator), [`app/ingestion/pipeline.py`](https://github.com/adityakumar0009/soverign-ai/blob/main/app/ingestion/pipeline.py) (Processing Pipeline), [`app/parsers/pdf/parser.py`](https://github.com/adityakumar0009/soverign-ai/blob/main/app/parsers/pdf/parser.py) (PDF Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_app["Application Setup<br/>[main.py]"]
  node_upload["Upload Route<br/>[upload.py]"]
  node_health["Health Route<br/>[health.py]"]
end

subgraph group_ingestion["Ingestion"]
  node_orchestrator["Ingestion Orchestrator<br/>[orchestrator.py]"]
  node_registry["Parser Registry<br/>[registry.py]"]
  node_pipeline["Processing Pipeline<br/>[pipeline.py]"]
  node_normalizer["Content Normalizer<br/>[normalizer.py]"]
  node_validator["Document Validator<br/>[validator.py]"]
end

subgraph group_parsers["Format Parsers"]
  node_parser_base["Parser Base<br/>[parser.py]"]
  node_pdf["PDF Parser<br/>[parser.py]"]
  node_docx["DOCX Parser"]
  node_excel["Excel Parser"]
  node_image["Image Parser"]
  node_pptx["PowerPoint Parser"]
  node_txt["Text Parser"]
end

subgraph group_models["Data Models"]
  node_document["Document Schema<br/>[document.py]"]
  node_entity["Entity Schema<br/>[entity.py]"]
  node_metadata["Metadata Schema<br/>[metadata.py]"]
  node_relationship["Relationship Schema<br/>[relationship.py]"]
  node_table["Table Schema<br/>[table.py]"]
end

node_client(("API Client"))

node_app -->|"registers route"| node_upload
node_app -->|"registers route"| node_health
node_client -.->|"submits file"| node_upload
node_upload -.->|"hands off"| node_orchestrator
node_orchestrator -->|"uses registry"| node_registry
node_orchestrator -.->|"runs processing"| node_pipeline
node_pipeline -.->|"normalizes"| node_normalizer
node_pipeline -.->|"validates"| node_validator
node_registry -.->|"selects parser"| node_pdf
node_registry -.->|"selects parser"| node_docx
node_registry -.->|"selects parser"| node_excel
node_registry -.->|"selects parser"| node_image
node_registry -.->|"selects parser"| node_pptx
node_registry -.->|"selects parser"| node_txt
node_pdf -->|"implements parser"| node_parser_base
node_pdf -->|"produces schema"| node_document
node_normalizer -.->|"normalizes to"| node_document
node_validator -.->|"validates schema"| node_document

click node_app "https://github.com/adityakumar0009/soverign-ai/blob/main/app/main.py"
click node_upload "https://github.com/adityakumar0009/soverign-ai/blob/main/app/api/routes/upload.py"
click node_health "https://github.com/adityakumar0009/soverign-ai/blob/main/app/api/routes/health.py"
click node_orchestrator "https://github.com/adityakumar0009/soverign-ai/blob/main/app/ingestion/orchestrator.py"
click node_registry "https://github.com/adityakumar0009/soverign-ai/blob/main/app/ingestion/registry.py"
click node_pipeline "https://github.com/adityakumar0009/soverign-ai/blob/main/app/ingestion/pipeline.py"
click node_normalizer "https://github.com/adityakumar0009/soverign-ai/blob/main/app/ingestion/normalizer.py"
click node_validator "https://github.com/adityakumar0009/soverign-ai/blob/main/app/ingestion/validator.py"
click node_parser_base "https://github.com/adityakumar0009/soverign-ai/blob/main/app/parsers/base/parser.py"
click node_pdf "https://github.com/adityakumar0009/soverign-ai/blob/main/app/parsers/pdf/parser.py"
click node_docx "https://github.com/adityakumar0009/soverign-ai/tree/main/app/parsers/docx"
click node_excel "https://github.com/adityakumar0009/soverign-ai/tree/main/app/parsers/excel"
click node_image "https://github.com/adityakumar0009/soverign-ai/tree/main/app/parsers/image"
click node_pptx "https://github.com/adityakumar0009/soverign-ai/tree/main/app/parsers/pptx"
click node_txt "https://github.com/adityakumar0009/soverign-ai/tree/main/app/parsers/txt"
click node_document "https://github.com/adityakumar0009/soverign-ai/blob/main/app/schemas/document.py"
click node_entity "https://github.com/adityakumar0009/soverign-ai/blob/main/app/schemas/entity.py"
click node_metadata "https://github.com/adityakumar0009/soverign-ai/blob/main/app/schemas/metadata.py"
click node_relationship "https://github.com/adityakumar0009/soverign-ai/blob/main/app/schemas/relationship.py"
click node_table "https://github.com/adityakumar0009/soverign-ai/blob/main/app/schemas/table.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_app,node_upload,node_health,node_client toneBlue
class node_orchestrator,node_registry,node_pipeline,node_normalizer,node_validator toneAmber
class node_parser_base,node_pdf,node_docx,node_excel,node_image,node_pptx,node_txt toneMint
class node_document,node_entity,node_metadata,node_relationship,node_table toneRose
```

## Components

### API

- [Application Setup](https://github.com/adityakumar0009/soverign-ai/blob/main/app/main.py): `app/main.py`
- [Upload Route](https://github.com/adityakumar0009/soverign-ai/blob/main/app/api/routes/upload.py): `app/api/routes/upload.py`
- [Health Route](https://github.com/adityakumar0009/soverign-ai/blob/main/app/api/routes/health.py): `app/api/routes/health.py`

### Ingestion

- [Ingestion Orchestrator](https://github.com/adityakumar0009/soverign-ai/blob/main/app/ingestion/orchestrator.py): `app/ingestion/orchestrator.py`
- [Parser Registry](https://github.com/adityakumar0009/soverign-ai/blob/main/app/ingestion/registry.py): `app/ingestion/registry.py`
- [Processing Pipeline](https://github.com/adityakumar0009/soverign-ai/blob/main/app/ingestion/pipeline.py): `app/ingestion/pipeline.py`
- [Content Normalizer](https://github.com/adityakumar0009/soverign-ai/blob/main/app/ingestion/normalizer.py): `app/ingestion/normalizer.py`
- [Document Validator](https://github.com/adityakumar0009/soverign-ai/blob/main/app/ingestion/validator.py): `app/ingestion/validator.py`

### Format Parsers

- [Parser Base](https://github.com/adityakumar0009/soverign-ai/blob/main/app/parsers/base/parser.py): `app/parsers/base/parser.py`
- [PDF Parser](https://github.com/adityakumar0009/soverign-ai/blob/main/app/parsers/pdf/parser.py): `app/parsers/pdf/parser.py`
- [DOCX Parser](https://github.com/adityakumar0009/soverign-ai/tree/main/app/parsers/docx): `app/parsers/docx`
- [Excel Parser](https://github.com/adityakumar0009/soverign-ai/tree/main/app/parsers/excel): `app/parsers/excel`
- [Image Parser](https://github.com/adityakumar0009/soverign-ai/tree/main/app/parsers/image): `app/parsers/image`
- [PowerPoint Parser](https://github.com/adityakumar0009/soverign-ai/tree/main/app/parsers/pptx): `app/parsers/pptx`
- [Text Parser](https://github.com/adityakumar0009/soverign-ai/tree/main/app/parsers/txt): `app/parsers/txt`

### Data Models

- [Document Schema](https://github.com/adityakumar0009/soverign-ai/blob/main/app/schemas/document.py): `app/schemas/document.py`
- [Entity Schema](https://github.com/adityakumar0009/soverign-ai/blob/main/app/schemas/entity.py): `app/schemas/entity.py`
- [Metadata Schema](https://github.com/adityakumar0009/soverign-ai/blob/main/app/schemas/metadata.py): `app/schemas/metadata.py`
- [Relationship Schema](https://github.com/adityakumar0009/soverign-ai/blob/main/app/schemas/relationship.py): `app/schemas/relationship.py`
- [Table Schema](https://github.com/adityakumar0009/soverign-ai/blob/main/app/schemas/table.py): `app/schemas/table.py`

### Other components

- **API Client**

## Connections

- Application Setup → Upload Route: registers route (evidence: `app/main.py`)
- Application Setup → Health Route: registers route (evidence: `app/main.py`)
- API Client → Upload Route: submits file
- Upload Route → Ingestion Orchestrator: hands off
- Ingestion Orchestrator → Parser Registry: uses registry (evidence: `app/ingestion/orchestrator.py`)
- Ingestion Orchestrator → Processing Pipeline: runs processing
- Processing Pipeline → Content Normalizer: normalizes
- Processing Pipeline → Document Validator: validates
- Parser Registry → PDF Parser: selects parser
- Parser Registry → DOCX Parser: selects parser
- Parser Registry → Excel Parser: selects parser
- Parser Registry → Image Parser: selects parser
- Parser Registry → PowerPoint Parser: selects parser
- Parser Registry → Text Parser: selects parser
- PDF Parser → Parser Base: implements parser (evidence: `app/parsers/pdf/parser.py`)
- PDF Parser → Document Schema: produces schema (evidence: `app/parsers/pdf/parser.py`)
- Content Normalizer → Document Schema: normalizes to
- Document Validator → Document Schema: validates schema
