How elsahu96/sidneysatorus works
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: service Services · main.tsx SPA shell · pages Pages · components Workspaces
Components 20
Frontend
React/Vite single-page app and client-side workflow layer
- SPA shell · Bootstraps the client app, routing, and global UI state
frontend/src/main.tsx - Pages · Top-level screens for login, admin, sessions, cases, and dark web workflows
frontend/src/pages - Workspaces · Chat, reports, citations, maps, and report templates
frontend/src/components - API client · Thin browser-side API wrappers and service adapters
frontend/src/api - Hooks · Auth and workflow hooks that isolate UI state from transport details
frontend/src/hooks - Auth boundary · Client authentication guard and Firebase integration
frontend/src/firebase.js - Exports · PDF export and bundled reference documents for report-centric workflows
frontend/src/lib/pdfExport.ts - Static docs · Shipped documents and static assets surfaced in the UI
frontend/public/documents
Backend
FastAPI service, orchestration, and data access
- API app · FastAPI application startup and local run wrapper
backend/src/api/main.py - API routes · Workflow-focused endpoints for users, sessions, cases, workspace, reports, investigate, and quick search
backend/src/api - Services · Auth, tenant/session handling, and investigation coordination
backend/src/service - Runner · Executes investigation jobs and bridges API requests to the analysis pipeline
backend/src/service/investigate_runner.py - Graph engine · Multi-step agent flow for planning, research, analysis, and writing
backend/src/graph - Grading · Source attribution, corroboration, and credibility scoring with curated media datasets
backend/src/graph/grading - Tools · News, URL-to-page, and writing tools used by the graph pipeline
backend/src/graph/tools - Data layer · Relational, search, vector, cache, and factory modules for persistence and retrieval
backend/src/data - Storage · Storage abstractions and factory for report/file persistence
backend/src/storage.py - Report model · Shared backend model for rendered report content and structured output
backend/src/models/report.py
Infrastructure
Deployment, containerization, and schema management
- Prisma schema · Versioned database schema and migrations for sessions, messages, references, and tenants
backend/prisma/schema.prisma - Deploy · Docker, compose, and Cloud Build/GitHub Actions deployment assets
docker-compose.yml
Connections 21
- 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