# rlpalomo25/ragseo-platform architecture

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

- Interactive diagram: https://gitdiagram.com/rlpalomo25/ragseo-platform
- Repository: https://github.com/rlpalomo25/ragseo-platform

## Overview

RAGSEO is a content-production platform that grounds AI-generated content in an ingested doctrine library and supports review, job tracking, and performance learning. Its main workflow is a content request routed through retrieval and agent processing, then exposed as a job result. Separate workflows ingest doctrine and external market data. The README documents hybrid retrieval and optional embedding providers; excerpts show selected ingestion, routing, task, and frontend behavior, so uncertain internal wiring is omitted.

Main entry points: [`backend/app/database.py`](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/database.py) (PostgreSQL + pgvector), [`backend/app/main.py`](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/services/doc_ingestion.py`](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/doc_ingestion.py) (Doctrine ingestion), [`backend/app/routers/ingest.py`](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/routers/ingest.py) (Ingest endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interface"]
  node_web["Next.js app"]
  node_ingest_hook["Ingest controls<br/>[useIngest.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and identity"]
  node_main["FastAPI app<br/>[main.py]"]
  node_agents_api["Agent endpoints<br/>[agents.py]"]
  node_ingest_api["Ingest endpoints<br/>[ingest.py]"]
  node_auth_api["Auth endpoints<br/>[auth.py]"]
  node_auth_service["Session service<br/>[auth_service.py]"]
  node_jobs_api["Job endpoints<br/>[jobs.py]"]
end

subgraph group_pipeline["Agent workflow"]
  node_tasks["Celery tasks<br/>[tasks.py]"]
  node_orchestrator["Job orchestration<br/>[orchestrator.py]"]
  node_agent_runner["Agent runner<br/>[agent_runner.py]"]
  node_router_agent["Request router<br/>[router.py]"]
  node_writer["Content writer<br/>[writer.py]"]
  node_auditor["Content auditor<br/>[auditor.py]"]
end

subgraph group_knowledge["Knowledge and data"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
  node_ingestion["Doctrine ingestion<br/>[doc_ingestion.py]"]
  node_chunking["Document chunking<br/>[chunking.py]"]
  node_embeddings["Embedding service<br/>[embeddings.py]"]
  node_external_ingest["Market data import<br/>[external_ingest.py]"]
  node_learning["Performance learning<br/>[learning_loop.py]"]
  node_database[("PostgreSQL + pgvector<br/>[database.py]")]
end

subgraph group_integrations["External integrations"]
  node_queue["Redis / Celery queue<br/>[celery_app.py]"]
  node_embedding_provider["Ollama / Voyage AI"]
  node_anthropic["Anthropic Claude"]
end

node_user(("Content user"))
node_doctrine_files["Doctrine corpus"]

node_user -->|"submits request"| node_web
node_web -->|"calls API"| node_api_client
node_api_client -->|"HTTP requests"| node_main
node_main -->|"mounts routes"| node_agents_api
node_main -->|"mounts routes"| node_ingest_api
node_main -->|"mounts routes"| node_auth_api
node_main -->|"mounts routes"| node_jobs_api
node_agents_api -->|"dispatches tasks"| node_queue
node_queue -->|"runs tasks"| node_tasks
node_tasks -->|"runs agent"| node_agent_runner
node_tasks -->|"advances job"| node_orchestrator
node_agent_runner -->|"invokes agent"| node_router_agent
node_router_agent -->|"retrieves doctrine"| node_retrieval
node_router_agent -->|"loads performance context"| node_learning
node_router_agent -->|"requests completion"| node_anthropic
node_writer -->|"requests completion"| node_anthropic
node_auditor -->|"requests completion"| node_anthropic
node_retrieval -->|"searches chunks"| node_database
node_ingest_hook -->|"calls ingest API"| node_api_client
node_ingest_api -->|"ingests doctrine"| node_ingestion
node_ingestion -->|"reads files"| node_doctrine_files
node_ingestion -->|"creates chunks"| node_chunking
node_ingestion -->|"embeds chunks"| node_embeddings
node_ingestion -->|"writes documents"| node_database
node_embeddings -.->|"requests vectors"| node_embedding_provider
node_ingest_api -->|"imports exports"| node_external_ingest
node_external_ingest -->|"stores market data"| node_database
node_ingest_api -->|"snapshots publications"| node_learning
node_learning -->|"reads and writes"| node_database
node_auth_api -->|"manages sessions"| node_auth_service
node_auth_service -->|"reads and writes"| node_database
node_jobs_api -->|"reads job state"| node_database

click node_web "https://github.com/rlpalomo25/ragseo-platform/tree/main/frontend/src/app"
click node_ingest_hook "https://github.com/rlpalomo25/ragseo-platform/blob/main/frontend/src/lib/hooks/useIngest.ts"
click node_api_client "https://github.com/rlpalomo25/ragseo-platform/blob/main/frontend/src/lib/api.ts"
click node_main "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/main.py"
click node_agents_api "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/routers/agents.py"
click node_ingest_api "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/routers/ingest.py"
click node_auth_api "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/routers/auth.py"
click node_auth_service "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/auth_service.py"
click node_jobs_api "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/routers/jobs.py"
click node_tasks "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/tasks.py"
click node_orchestrator "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/orchestrator.py"
click node_agent_runner "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/agent_runner.py"
click node_router_agent "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/agents/router.py"
click node_writer "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/agents/writer.py"
click node_auditor "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/agents/auditor.py"
click node_retrieval "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/retrieval.py"
click node_ingestion "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/doc_ingestion.py"
click node_chunking "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/chunking.py"
click node_embeddings "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/embeddings.py"
click node_external_ingest "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/external_ingest.py"
click node_learning "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/learning_loop.py"
click node_database "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/database.py"
click node_queue "https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/celery_app.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_web,node_ingest_hook,node_api_client,node_user toneBlue
class node_main,node_agents_api,node_ingest_api,node_auth_api,node_auth_service,node_jobs_api toneAmber
class node_tasks,node_orchestrator,node_agent_runner,node_router_agent,node_writer,node_auditor toneMint
class node_retrieval,node_ingestion,node_chunking,node_embeddings,node_external_ingest,node_learning,node_database toneRose
class node_queue,node_embedding_provider,node_anthropic,node_doctrine_files toneIndigo
```

## Components

### User interface

- [Next.js app](https://github.com/rlpalomo25/ragseo-platform/tree/main/frontend/src/app): `frontend/src/app`
- [Ingest controls](https://github.com/rlpalomo25/ragseo-platform/blob/main/frontend/src/lib/hooks/useIngest.ts): `frontend/src/lib/hooks/useIngest.ts`
- [API client](https://github.com/rlpalomo25/ragseo-platform/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and identity

- [FastAPI app](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/main.py): `backend/app/main.py`
- [Agent endpoints](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/routers/agents.py): `backend/app/routers/agents.py`
- [Ingest endpoints](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/routers/ingest.py): `backend/app/routers/ingest.py`
- [Auth endpoints](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Session service](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Job endpoints](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/routers/jobs.py): `backend/app/routers/jobs.py`

### Agent workflow

- [Celery tasks](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/tasks.py): `backend/app/tasks.py`
- [Job orchestration](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/orchestrator.py): `backend/app/services/orchestrator.py`
- [Agent runner](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/agent_runner.py): `backend/app/services/agent_runner.py`
- [Request router](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/agents/router.py): `backend/app/services/agents/router.py`
- [Content writer](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/agents/writer.py): `backend/app/services/agents/writer.py`
- [Content auditor](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/agents/auditor.py): `backend/app/services/agents/auditor.py`

### Knowledge and data

- [Hybrid retrieval](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/retrieval.py): `backend/app/services/retrieval.py`
- [Doctrine ingestion](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/doc_ingestion.py): `backend/app/services/doc_ingestion.py`
- [Document chunking](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/chunking.py): `backend/app/services/chunking.py`
- [Embedding service](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/embeddings.py): `backend/app/services/embeddings.py`
- [Market data import](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/external_ingest.py): `backend/app/services/external_ingest.py`
- [Performance learning](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/services/learning_loop.py): `backend/app/services/learning_loop.py`
- [PostgreSQL + pgvector](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/database.py): `backend/app/database.py`

### External integrations

- [Redis / Celery queue](https://github.com/rlpalomo25/ragseo-platform/blob/main/backend/app/celery_app.py): `backend/app/celery_app.py`
- **Ollama / Voyage AI**
- **Anthropic Claude**

### Other components

- **Content user**
- **Doctrine corpus**

## Connections

- Content user → Next.js app: submits request
- Next.js app → API client: calls API
- API client → FastAPI app: HTTP requests
- FastAPI app → Agent endpoints: mounts routes
- FastAPI app → Ingest endpoints: mounts routes
- FastAPI app → Auth endpoints: mounts routes
- FastAPI app → Job endpoints: mounts routes
- Agent endpoints → Redis / Celery queue: dispatches tasks
- Redis / Celery queue → Celery tasks: runs tasks
- Celery tasks → Agent runner: runs agent
- Celery tasks → Job orchestration: advances job
- Agent runner → Request router: invokes agent
- Request router → Hybrid retrieval: retrieves doctrine
- Request router → Performance learning: loads performance context
- Request router → Anthropic Claude: requests completion
- Content writer → Anthropic Claude: requests completion
- Content auditor → Anthropic Claude: requests completion
- Hybrid retrieval → PostgreSQL + pgvector: searches chunks
- Ingest controls → API client: calls ingest API
- Ingest endpoints → Doctrine ingestion: ingests doctrine
- Doctrine ingestion → Doctrine corpus: reads files
- Doctrine ingestion → Document chunking: creates chunks
- Doctrine ingestion → Embedding service: embeds chunks
- Doctrine ingestion → PostgreSQL + pgvector: writes documents
- Embedding service → Ollama / Voyage AI: requests vectors
- Ingest endpoints → Market data import: imports exports
- Market data import → PostgreSQL + pgvector: stores market data
- Ingest endpoints → Performance learning: snapshots publications
- Performance learning → PostgreSQL + pgvector: reads and writes
- Auth endpoints → Session service: manages sessions
- Session service → PostgreSQL + pgvector: reads and writes
- Job endpoints → PostgreSQL + pgvector: reads job state