# parts345/inkloom-ai architecture

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

- Interactive diagram: https://gitdiagram.com/parts345/inkloom-ai
- Repository: https://github.com/parts345/inkloom-ai

## Overview

Inkloom AI is a pre-publication brand-governance workspace: creators submit content, the backend analyzes it, and users review findings and decisions; separate views expose brand knowledge and governance analytics. The README describes extraction, deterministic checks, LLM verification, and persistence as interface stubs, so the graph shows those documented stages without assuming implementation details beyond the excerpts. Frontend-to-backend links are marked unverified because the excerpts do not show the complete request/route mapping.

Main entry points: [`backend/app/routers/submissions.py`](https://github.com/parts345/inkloom-ai/blob/main/backend/app/routers/submissions.py) (Submission routes), [`frontend/src/api.ts`](https://github.com/parts345/inkloom-ai/blob/main/frontend/src/api.ts) (API client), [`frontend/src/App.tsx`](https://github.com/parts345/inkloom-ai/blob/main/frontend/src/App.tsx) (Workspace navigation), [`backend/app/services/orchestrator.py`](https://github.com/parts345/inkloom-ai/blob/main/backend/app/services/orchestrator.py) (Analysis orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace UI"]
  node_app["Workspace navigation<br/>[App.tsx]"]
  node_new["New submission"]
  node_review["Review workspace"]
  node_knowledge["Brand knowledge"]
  node_analytics["Governance analytics"]
  node_ui["Review components<br/>[ui.tsx]"]
end

subgraph group_api["Submission API"]
  node_client["API client<br/>[api.ts]"]
  node_mock["Mock API<br/>[mock.ts]"]
  node_routes["Submission routes<br/>[submissions.py]"]
  node_roles["Demo roles<br/>[demo.py]"]
  node_contracts["API contracts<br/>[schemas.py]"]
end

subgraph group_analysis["Content Analysis"]
  node_orchestrator["Analysis orchestrator<br/>[orchestrator.py]"]
  node_extract["Content extraction<br/>[extraction.py]"]
  node_checks["Deterministic checks<br/>[deterministic.py]"]
  node_verify["LLM verification<br/>[verification.py]"]
end

subgraph group_state["Governance State"]
  node_persistence["Analysis persistence<br/>[persistence.py]"]
  node_database[("SQL database<br/>[database.py]")]
  node_models["Governance records<br/>[models.py]"]
  node_seed["Demo workspace seed<br/>[seed.py]"]
end

node_user(("Workspace user"))
node_backend["FastAPI application<br/>[main.py]"]

node_user -->|"uses"| node_app
node_app -->|"shows"| node_new
node_app -->|"shows"| node_review
node_app -->|"shows"| node_knowledge
node_app -->|"shows"| node_analytics
node_app -->|"loads submissions"| node_client
node_review -->|"renders"| node_ui
node_review -.->|"requests actions"| node_client
node_new -.->|"creates submission"| node_client
node_knowledge -->|"requests knowledge"| node_client
node_analytics -->|"requests data"| node_client
node_client -->|"delegates in mock mode"| node_mock
node_client -.->|"sends HTTP requests"| node_routes
node_backend -->|"registers"| node_routes
node_backend -->|"registers"| node_roles
node_routes -->|"resolves actor"| node_roles
node_routes -->|"analyzes submission"| node_orchestrator
node_routes -->|"reads and writes"| node_persistence
node_routes -->|"uses sessions"| node_database
node_routes -->|"queries records"| node_models
node_routes -->|"validates payloads"| node_contracts
node_orchestrator -->|"extracts units"| node_extract
node_orchestrator -->|"runs checks"| node_checks
node_orchestrator -->|"verifies units"| node_verify
node_orchestrator -.->|"persists results"| node_persistence
node_orchestrator -->|"uses data types"| node_contracts
node_persistence -->|"opens sessions"| node_database
node_persistence -->|"maps records"| node_models
node_persistence -->|"builds responses"| node_contracts
node_verify -->|"loads knowledge"| node_models
node_verify -->|"builds findings"| node_contracts
node_backend -->|"initializes"| node_database
node_backend -->|"loads demo data"| node_seed
node_seed -->|"stores seed data"| node_persistence
node_seed -->|"creates records"| node_models
node_seed -->|"uses sessions"| node_database

click node_app "https://github.com/parts345/inkloom-ai/blob/main/frontend/src/App.tsx"
click node_new "https://github.com/parts345/inkloom-ai/blob/main/frontend/src/pages/NewSubmissionView.tsx"
click node_review "https://github.com/parts345/inkloom-ai/blob/main/frontend/src/pages/SubmissionReviewView.tsx"
click node_knowledge "https://github.com/parts345/inkloom-ai/blob/main/frontend/src/pages/BrandKnowledgeView.tsx"
click node_analytics "https://github.com/parts345/inkloom-ai/blob/main/frontend/src/pages/GovernanceAnalyticsView.tsx"
click node_ui "https://github.com/parts345/inkloom-ai/blob/main/frontend/src/pages/ui.tsx"
click node_client "https://github.com/parts345/inkloom-ai/blob/main/frontend/src/api.ts"
click node_mock "https://github.com/parts345/inkloom-ai/blob/main/frontend/src/mock.ts"
click node_routes "https://github.com/parts345/inkloom-ai/blob/main/backend/app/routers/submissions.py"
click node_roles "https://github.com/parts345/inkloom-ai/blob/main/backend/app/routers/demo.py"
click node_contracts "https://github.com/parts345/inkloom-ai/blob/main/backend/app/schemas.py"
click node_orchestrator "https://github.com/parts345/inkloom-ai/blob/main/backend/app/services/orchestrator.py"
click node_extract "https://github.com/parts345/inkloom-ai/blob/main/backend/app/services/extraction.py"
click node_checks "https://github.com/parts345/inkloom-ai/blob/main/backend/app/services/deterministic.py"
click node_verify "https://github.com/parts345/inkloom-ai/blob/main/backend/app/services/verification.py"
click node_persistence "https://github.com/parts345/inkloom-ai/blob/main/backend/app/services/persistence.py"
click node_database "https://github.com/parts345/inkloom-ai/blob/main/backend/app/database.py"
click node_models "https://github.com/parts345/inkloom-ai/blob/main/backend/app/models.py"
click node_seed "https://github.com/parts345/inkloom-ai/blob/main/backend/app/seed.py"
click node_backend "https://github.com/parts345/inkloom-ai/blob/main/backend/app/main.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_new,node_review,node_knowledge,node_analytics,node_ui,node_user toneBlue
class node_client,node_mock,node_routes,node_roles,node_contracts toneAmber
class node_orchestrator,node_extract,node_checks,node_verify,node_backend toneMint
class node_persistence,node_database,node_models,node_seed toneRose
```

## Components

### Workspace UI

- [Workspace navigation](https://github.com/parts345/inkloom-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [New submission](https://github.com/parts345/inkloom-ai/blob/main/frontend/src/pages/NewSubmissionView.tsx): `frontend/src/pages/NewSubmissionView.tsx`
- [Review workspace](https://github.com/parts345/inkloom-ai/blob/main/frontend/src/pages/SubmissionReviewView.tsx): `frontend/src/pages/SubmissionReviewView.tsx`
- [Brand knowledge](https://github.com/parts345/inkloom-ai/blob/main/frontend/src/pages/BrandKnowledgeView.tsx): `frontend/src/pages/BrandKnowledgeView.tsx`
- [Governance analytics](https://github.com/parts345/inkloom-ai/blob/main/frontend/src/pages/GovernanceAnalyticsView.tsx): `frontend/src/pages/GovernanceAnalyticsView.tsx`
- [Review components](https://github.com/parts345/inkloom-ai/blob/main/frontend/src/pages/ui.tsx): `frontend/src/pages/ui.tsx`

### Submission API

- [API client](https://github.com/parts345/inkloom-ai/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Mock API](https://github.com/parts345/inkloom-ai/blob/main/frontend/src/mock.ts): `frontend/src/mock.ts`
- [Submission routes](https://github.com/parts345/inkloom-ai/blob/main/backend/app/routers/submissions.py): `backend/app/routers/submissions.py`
- [Demo roles](https://github.com/parts345/inkloom-ai/blob/main/backend/app/routers/demo.py): `backend/app/routers/demo.py`
- [API contracts](https://github.com/parts345/inkloom-ai/blob/main/backend/app/schemas.py): `backend/app/schemas.py`

### Content Analysis

- [Analysis orchestrator](https://github.com/parts345/inkloom-ai/blob/main/backend/app/services/orchestrator.py): `backend/app/services/orchestrator.py`
- [Content extraction](https://github.com/parts345/inkloom-ai/blob/main/backend/app/services/extraction.py): `backend/app/services/extraction.py`
- [Deterministic checks](https://github.com/parts345/inkloom-ai/blob/main/backend/app/services/deterministic.py): `backend/app/services/deterministic.py`
- [LLM verification](https://github.com/parts345/inkloom-ai/blob/main/backend/app/services/verification.py): `backend/app/services/verification.py`

### Governance State

- [Analysis persistence](https://github.com/parts345/inkloom-ai/blob/main/backend/app/services/persistence.py): `backend/app/services/persistence.py`
- [SQL database](https://github.com/parts345/inkloom-ai/blob/main/backend/app/database.py): `backend/app/database.py`
- [Governance records](https://github.com/parts345/inkloom-ai/blob/main/backend/app/models.py): `backend/app/models.py`
- [Demo workspace seed](https://github.com/parts345/inkloom-ai/blob/main/backend/app/seed.py): `backend/app/seed.py`

### Other components

- **Workspace user**
- [FastAPI application](https://github.com/parts345/inkloom-ai/blob/main/backend/app/main.py): `backend/app/main.py`

## Connections

- Workspace user → Workspace navigation: uses (evidence: `README.md`)
- Workspace navigation → New submission: shows (evidence: `frontend/src/App.tsx`)
- Workspace navigation → Review workspace: shows (evidence: `frontend/src/App.tsx`)
- Workspace navigation → Brand knowledge: shows (evidence: `frontend/src/App.tsx`)
- Workspace navigation → Governance analytics: shows (evidence: `frontend/src/App.tsx`)
- Workspace navigation → API client: loads submissions (evidence: `frontend/src/App.tsx`)
- Review workspace → Review components: renders (evidence: `frontend/src/pages/SubmissionReviewView.tsx`)
- Review workspace → API client: requests actions (evidence: `frontend/src/pages/SubmissionReviewView.tsx`)
- New submission → API client: creates submission (evidence: `frontend/src/pages/NewSubmissionView.tsx`)
- Brand knowledge → API client: requests knowledge (evidence: `frontend/src/pages/BrandKnowledgeView.tsx`)
- Governance analytics → API client: requests data (evidence: `frontend/src/pages/GovernanceAnalyticsView.tsx`)
- API client → Mock API: delegates in mock mode (evidence: `frontend/src/api.ts`)
- API client → Submission routes: sends HTTP requests
- FastAPI application → Submission routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Demo roles: registers (evidence: `backend/app/main.py`)
- Submission routes → Demo roles: resolves actor (evidence: `backend/app/routers/submissions.py`)
- Submission routes → Analysis orchestrator: analyzes submission (evidence: `backend/app/routers/submissions.py`)
- Submission routes → Analysis persistence: reads and writes (evidence: `backend/app/routers/submissions.py`)
- Submission routes → SQL database: uses sessions (evidence: `backend/app/routers/submissions.py`)
- Submission routes → Governance records: queries records (evidence: `backend/app/routers/submissions.py`)
- Submission routes → API contracts: validates payloads (evidence: `backend/app/routers/submissions.py`)
- Analysis orchestrator → Content extraction: extracts units (evidence: `backend/app/services/orchestrator.py`)
- Analysis orchestrator → Deterministic checks: runs checks (evidence: `backend/app/services/orchestrator.py`)
- Analysis orchestrator → LLM verification: verifies units (evidence: `backend/app/services/orchestrator.py`)
- Analysis orchestrator → Analysis persistence: persists results (evidence: `backend/app/services/orchestrator.py`)
- Analysis orchestrator → API contracts: uses data types (evidence: `backend/app/services/orchestrator.py`)
- Analysis persistence → SQL database: opens sessions (evidence: `backend/app/services/persistence.py`)
- Analysis persistence → Governance records: maps records (evidence: `backend/app/services/persistence.py`)
- Analysis persistence → API contracts: builds responses (evidence: `backend/app/services/persistence.py`)
- LLM verification → Governance records: loads knowledge (evidence: `backend/app/services/verification.py`)
- LLM verification → API contracts: builds findings (evidence: `backend/app/services/verification.py`)
- FastAPI application → SQL database: initializes (evidence: `backend/app/main.py`)
- FastAPI application → Demo workspace seed: loads demo data (evidence: `backend/app/main.py`)
- Demo workspace seed → Analysis persistence: stores seed data (evidence: `backend/app/seed.py`)
- Demo workspace seed → Governance records: creates records (evidence: `backend/app/seed.py`)
- Demo workspace seed → SQL database: uses sessions (evidence: `backend/app/seed.py`)
