# elsahu96/sidneysatorus architecture

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

- Interactive diagram: https://gitdiagram.com/elsahu96/sidneysatorus
- Repository: https://github.com/elsahu96/sidneysatorus

## Overview

1. **Overall shape**
   - This is a two-tier monorepo: a **React/Vite frontend** and a **Python/FastAPI backend**, with shared deployment/configuration assets at the repo root.
   - The product is centered on **investigation/report workflows** rather than a generic CRUD app.

2. **Frontend boundary**
   - The frontend is a **single-page app** built with **TypeScript, React, Vite, Tailwind, and shadcn/ui**.
   - `src/pages` defines the major screens: login, admin, session history, case details, case files, dark web, and the main index view.
   - `src/components` contains the user-facing workspaces: chat, report rendering, citations/references, maps/visualizations, and custom report templates.

3. **Frontend data access**
   - The browser talks to the backend through a thin API layer in `src/api` and `src/services`.
   - Hooks such as `useChat`, `useInvestigation`, and `useSessionHistory` wrap those calls and keep UI state isolated from transport details.
   - `AuthGuard`, `useAuth`, and `firebase.js` show that **Firebase-based auth** is part of the client-side boundary.

4. **Backend API layer**
   - The backend exposes grouped endpoints under `src/api`: `user`, `sessions`, `cases`, `workspace`, `report`, `investigate`, and `quick_search`.
   - This suggests the API is organized around **workflow domains** instead of a single generic resource model.
   - `src/api/main.py` is the FastAPI entry point; `run.py` is the local launch wrapper.

5. **Backend orchestration layer**
   - The service layer in `src/service` is where request handling becomes business logic:
     - `auth.py` for identity/session checks,
     - `chat_session_service.py` and `investigate_service.py` for workflow coordination,
     - `investigate_runner.py` for executing investigations,
     - `storage.py`, `db.py`, and `tenants.py` for infrastructure concerns.
   - This layer is the main boundary between HTTP/API concerns and the AI/data subsystems.

6. **AI research and report pipeline**
   - `src/graph` is the core analysis engine.
   - It contains agent/flow code, prompt files, middleware, tools, and grading logic, indicating a **multi-step LLM workflow** rather than a single prompt call.
   - The `agents`, `prompts`, and `tools` directories suggest separate stages for planning, research, analysis, and writing.
   - `src/graph/grading` applies source-quality and attribution checks using curated datasets such as MBFC, RSF, media type fallbacks, and COI flags.

7. **Data and retrieval subsystem**
   - `src/data` abstracts the backend’s data access patterns into **relational**, **search**, **vector**, and **cache** modules.
   - This implies the system combines structured persistence with retrieval-oriented lookups and precomputed caches.
   - The scripts `build_mbfc_cache.py` and `build_rsf_cache.py` reinforce that some source-quality data is prepared offline and loaded into runtime caches.

8. **Persistence and schema**
   - The repository includes `backend/prisma/schema.prisma` and multiple migrations, so the relational model is schema-managed and versioned.
   - The migration names show the backend evolved around **chat sessions** and **message/report references**, which are core persisted entities.
   - This persistence layer likely backs sessions, cases, reports, and tenant/user metadata.

9. **Storage and external integrations**
   - The project has explicit storage abstractions (`storage_factory.py`, `src/storage.py`, `src/service/storage.py`) and tests for **GCS report push**, so object storage is part of the architecture.
   - README and tests also show a **Cloud SQL proxy** workflow, so the backend expects a managed PostgreSQL instance in deployment/dev.
   - A news/research integration appears present through `src/graph/tools/asknews.py`, and URL/page fetching is handled as a tool rather than directly in the API.

10. **Deployment and runtime**
   - The system is containerized with separate **Dockerfiles** for frontend and backend, plus `docker-compose.yml` for local multi-service runs.
   - Cloud deployment is automated through **GitHub Actions** and **Cloud Build** configs under `.github/workflows` and `deploy/`.
   - The backend is Python-based (uv/pytest/prisma), while the frontend is Node-based (Vite/Bun/npm), so the repo cleanly separates runtimes.

11. **Static content and exports**
   - The frontend ships some static reference documents under `public/documents`, and there are report/export helpers in `src/lib/pdfExport.ts` and `scripts/get-report.ts`.
   - This indicates the UI is not only interactive but also supports **rendered report output** and document-centric workflows.

12. **High-level data flow**
   - Typical flow: user authenticates in the SPA → frontend calls the FastAPI backend → backend validates auth and loads tenant/session context → investigation/report logic runs through the graph pipeline → retrieval and grading consult structured data, search/vector/cache layers, and external tools → results are persisted and surfaced back to the UI as sessions, reports, citations, and visualizations.

Main entry points: [`backend/src/service`](https://github.com/elsahu96/sidneysatorus/tree/main/backend/src/service) (Services), [`frontend/src/main.tsx`](https://github.com/elsahu96/sidneysatorus/blob/main/frontend/src/main.tsx) (SPA shell), [`frontend/src/pages`](https://github.com/elsahu96/sidneysatorus/tree/main/frontend/src/pages) (Pages), [`frontend/src/components`](https://github.com/elsahu96/sidneysatorus/tree/main/frontend/src/components) (Workspaces)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["SPA shell<br/>react/vite app<br/>[main.tsx]"]
  node_frontend_pages["Pages<br/>screens"]
  node_frontend_workspaces["Workspaces<br/>ui components"]
  node_frontend_api["API client<br/>transport layer"]
  node_frontend_hooks["Hooks<br/>state adapters"]
  node_frontend_auth["Auth boundary<br/>firebase auth<br/>[firebase.js]"]
  node_frontend_export["Exports<br/>report output<br/>[pdfExport.ts]"]
  node_frontend_static["Static docs<br/>public assets"]
end

subgraph group_backend["Backend"]
  node_backend_entry["API app<br/>fastapi entrypoint<br/>[main.py]"]
  node_backend_routes["API routes<br/>domain endpoints"]
  node_backend_service["Services<br/>business logic"]
  node_backend_runner["Runner<br/>workflow executor"]
  node_backend_graph["Graph engine<br/>llm workflow"]
  node_backend_grading["Grading<br/>quality checks"]
  node_backend_tools["Tools"]
  node_backend_data["Data layer<br/>retrieval/storage"]
  node_backend_storage["Storage<br/>[storage.py]"]
  node_backend_models["Report model<br/>domain model<br/>[report.py]"]
end

subgraph group_infra["Infrastructure"]
  node_backend_prisma[("Prisma schema<br/>relational schema<br/>[schema.prisma]")]
  node_deploy["Deploy<br/>containers/cloud build<br/>[docker-compose.yml]"]
end

node_frontend_app -->|"routes to"| node_frontend_pages
node_frontend_app -->|"renders"| node_frontend_workspaces
node_frontend_pages -->|"calls"| node_frontend_api
node_frontend_workspaces -->|"uses"| node_frontend_hooks
node_frontend_hooks -->|"delegates"| node_frontend_api
node_frontend_auth -->|"guards"| node_frontend_hooks
node_frontend_workspaces -->|"exports"| node_frontend_export
node_frontend_pages -->|"protects"| node_frontend_auth
node_frontend_app -->|"serves"| node_frontend_static
node_frontend_api -->|"requests"| node_backend_entry
node_backend_entry -->|"mounts"| node_backend_routes
node_backend_routes -->|"delegates"| node_backend_service
node_backend_service -->|"orchestrates"| node_backend_runner
node_backend_runner -->|"executes"| node_backend_graph
node_backend_graph -->|"evaluates"| node_backend_grading
node_backend_graph -->|"uses"| node_backend_tools
node_backend_service -->|"loads"| node_backend_data
node_backend_service -->|"persists"| node_backend_storage
node_backend_data -->|"reads/writes"| node_backend_prisma
node_backend_storage -.->|"deploys with"| node_deploy
node_backend_routes -->|"returns"| node_backend_models

click node_frontend_app "https://github.com/elsahu96/sidneysatorus/blob/main/frontend/src/main.tsx"
click node_frontend_pages "https://github.com/elsahu96/sidneysatorus/tree/main/frontend/src/pages"
click node_frontend_workspaces "https://github.com/elsahu96/sidneysatorus/tree/main/frontend/src/components"
click node_frontend_api "https://github.com/elsahu96/sidneysatorus/tree/main/frontend/src/api"
click node_frontend_hooks "https://github.com/elsahu96/sidneysatorus/tree/main/frontend/src/hooks"
click node_frontend_auth "https://github.com/elsahu96/sidneysatorus/blob/main/frontend/src/firebase.js"
click node_frontend_export "https://github.com/elsahu96/sidneysatorus/blob/main/frontend/src/lib/pdfExport.ts"
click node_backend_entry "https://github.com/elsahu96/sidneysatorus/blob/main/backend/src/api/main.py"
click node_backend_routes "https://github.com/elsahu96/sidneysatorus/tree/main/backend/src/api"
click node_backend_service "https://github.com/elsahu96/sidneysatorus/tree/main/backend/src/service"
click node_backend_runner "https://github.com/elsahu96/sidneysatorus/blob/main/backend/src/service/investigate_runner.py"
click node_backend_graph "https://github.com/elsahu96/sidneysatorus/tree/main/backend/src/graph"
click node_backend_grading "https://github.com/elsahu96/sidneysatorus/tree/main/backend/src/graph/grading"
click node_backend_tools "https://github.com/elsahu96/sidneysatorus/tree/main/backend/src/graph/tools"
click node_backend_data "https://github.com/elsahu96/sidneysatorus/tree/main/backend/src/data"
click node_backend_storage "https://github.com/elsahu96/sidneysatorus/blob/main/backend/src/storage.py"
click node_backend_models "https://github.com/elsahu96/sidneysatorus/blob/main/backend/src/models/report.py"
click node_backend_prisma "https://github.com/elsahu96/sidneysatorus/blob/main/backend/prisma/schema.prisma"
click node_deploy "https://github.com/elsahu96/sidneysatorus/blob/main/docker-compose.yml"
click node_frontend_static "https://github.com/elsahu96/sidneysatorus/tree/main/frontend/public/documents"

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_frontend_app,node_frontend_pages,node_frontend_workspaces,node_frontend_api,node_frontend_hooks,node_frontend_auth,node_frontend_export,node_frontend_static toneBlue
class node_backend_entry,node_backend_routes,node_backend_service,node_backend_runner,node_backend_graph,node_backend_grading,node_backend_tools,node_backend_data,node_backend_storage,node_backend_models toneAmber
class node_backend_prisma,node_deploy toneMint
```

## Components

### Frontend

React/Vite single-page app and client-side workflow layer

- [SPA shell](https://github.com/elsahu96/sidneysatorus/blob/main/frontend/src/main.tsx): react/vite app · Bootstraps the client app, routing, and global UI state · `frontend/src/main.tsx`
- [Pages](https://github.com/elsahu96/sidneysatorus/tree/main/frontend/src/pages): screens · Top-level screens for login, admin, sessions, cases, and dark web workflows · `frontend/src/pages`
- [Workspaces](https://github.com/elsahu96/sidneysatorus/tree/main/frontend/src/components): ui components · Chat, reports, citations, maps, and report templates · `frontend/src/components`
- [API client](https://github.com/elsahu96/sidneysatorus/tree/main/frontend/src/api): transport layer · Thin browser-side API wrappers and service adapters · `frontend/src/api`
- [Hooks](https://github.com/elsahu96/sidneysatorus/tree/main/frontend/src/hooks): state adapters · Auth and workflow hooks that isolate UI state from transport details · `frontend/src/hooks`
- [Auth boundary](https://github.com/elsahu96/sidneysatorus/blob/main/frontend/src/firebase.js): firebase auth · Client authentication guard and Firebase integration · `frontend/src/firebase.js`
- [Exports](https://github.com/elsahu96/sidneysatorus/blob/main/frontend/src/lib/pdfExport.ts): report output · PDF export and bundled reference documents for report-centric workflows · `frontend/src/lib/pdfExport.ts`
- [Static docs](https://github.com/elsahu96/sidneysatorus/tree/main/frontend/public/documents): public assets · Shipped documents and static assets surfaced in the UI · `frontend/public/documents`

### Backend

FastAPI service, orchestration, and data access

- [API app](https://github.com/elsahu96/sidneysatorus/blob/main/backend/src/api/main.py): fastapi entrypoint · FastAPI application startup and local run wrapper · `backend/src/api/main.py`
- [API routes](https://github.com/elsahu96/sidneysatorus/tree/main/backend/src/api): domain endpoints · Workflow-focused endpoints for users, sessions, cases, workspace, reports, investigate, and quick search · `backend/src/api`
- [Services](https://github.com/elsahu96/sidneysatorus/tree/main/backend/src/service): business logic · Auth, tenant/session handling, and investigation coordination · `backend/src/service`
- [Runner](https://github.com/elsahu96/sidneysatorus/blob/main/backend/src/service/investigate_runner.py): workflow executor · Executes investigation jobs and bridges API requests to the analysis pipeline · `backend/src/service/investigate_runner.py`
- [Graph engine](https://github.com/elsahu96/sidneysatorus/tree/main/backend/src/graph): llm workflow · Multi-step agent flow for planning, research, analysis, and writing · `backend/src/graph`
- [Grading](https://github.com/elsahu96/sidneysatorus/tree/main/backend/src/graph/grading): quality checks · Source attribution, corroboration, and credibility scoring with curated media datasets · `backend/src/graph/grading`
- [Tools](https://github.com/elsahu96/sidneysatorus/tree/main/backend/src/graph/tools): external tools · News, URL-to-page, and writing tools used by the graph pipeline · `backend/src/graph/tools`
- [Data layer](https://github.com/elsahu96/sidneysatorus/tree/main/backend/src/data): retrieval/storage · Relational, search, vector, cache, and factory modules for persistence and retrieval · `backend/src/data`
- [Storage](https://github.com/elsahu96/sidneysatorus/blob/main/backend/src/storage.py): object storage · Storage abstractions and factory for report/file persistence · `backend/src/storage.py`
- [Report model](https://github.com/elsahu96/sidneysatorus/blob/main/backend/src/models/report.py): domain model · Shared backend model for rendered report content and structured output · `backend/src/models/report.py`

### Infrastructure

Deployment, containerization, and schema management

- [Prisma schema](https://github.com/elsahu96/sidneysatorus/blob/main/backend/prisma/schema.prisma): relational schema · Versioned database schema and migrations for sessions, messages, references, and tenants · `backend/prisma/schema.prisma`
- [Deploy](https://github.com/elsahu96/sidneysatorus/blob/main/docker-compose.yml): containers/cloud build · Docker, compose, and Cloud Build/GitHub Actions deployment assets · `docker-compose.yml`

## Connections

- SPA shell → Pages: routes to · App shell loads the major screens
- SPA shell → Workspaces: renders · Shell composes the investigation and reporting UI
- Pages → API client: calls · Screens request backend data through client wrappers
- Workspaces → Hooks: uses · Interactive workspaces rely on workflow hooks
- Hooks → API client: delegates · Hooks wrap API calls and local state
- Auth boundary → Hooks: guards · Authentication state gates the client workflow
- Workspaces → Exports: exports · Reports and references can be rendered or downloaded
- Pages → Auth boundary: protects · Login and route protection sit at the client boundary
- SPA shell → Static docs: serves · The SPA includes bundled documents and reference assets
- API client → API app: requests · Browser traffic targets the FastAPI application
- API app → API routes: mounts · Application entrypoint exposes grouped workflow endpoints
- API routes → Services: delegates · Route handlers hand off to business logic
- Services → Runner: orchestrates · Investigation services trigger workflow execution
- Runner → Graph engine: executes · Runner drives the multi-stage analysis pipeline
- Graph engine → Grading: evaluates · Pipeline consults quality and attribution grading
- Graph engine → Tools: uses · Agents call out to search, page fetch, and writing tools
- Services → Data layer: loads · Services access relational, search, vector, and cache layers
- Services → Storage: persists · Services push reports and files to storage backends
- Data layer → Prisma schema: reads/writes · Relational persistence is schema-managed via Prisma
- Storage → Deploy: deploys with · Storage and app runtimes are packaged for container/cloud deployment
- API routes → Report model: returns · API responses include structured report entities