# procoder1234556/aegis-imaging1 architecture

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

- Interactive diagram: https://gitdiagram.com/procoder1234556/aegis-imaging1
- Repository: https://github.com/procoder1234556/aegis-imaging1

## Overview

1. **What this repo is**
   - Aegis-Imaging is a split frontend/backend application for analyzing uploaded imaging data, running it through an automated review pipeline, and presenting a final outcome such as approved, rejected, or escalated.
   - The repo is organized around a single “case” lifecycle: upload → processing → verification/analysis → verdict → audit/history.

2. **Frontend boundary**
   - The `frontend/` directory is a React application that owns the user experience and case-state navigation.
   - It has route-level pages for login, upload, processing, verifying, final outcomes, billing, profile, API keys, dashboard, and audit detail.
   - `AuthContext` and `ProtectedRoute` define the authenticated UI boundary, while `ThemeContext` handles presentation state only.

3. **Backend boundary**
   - The `backend/` directory is a Python API service. `server.py` is the entrypoint, with `schemas.py` defining API payload contracts and router modules exposing feature-specific endpoints.
   - The backend is responsible for all business logic: authentication, persistence, model orchestration, reporting, and integration with external services.

4. **Core analysis pipeline**
   - The central architecture is an agent pipeline in `backend/agents/`.
   - The agent set is intentionally segmented by responsibility: `intake` gathers/normalizes input, `clinical` evaluates medical/semantic relevance, `forensics` handles integrity/abuse signals, `audit` records traceability, and `verdict` produces the final outcome.
   - `orchestrator.py` likely coordinates these agents in sequence or as a staged workflow, making it the main control point for case processing.

5. **Imaging and ML subsystem**
   - `hf_detectors.py` and `backend/data/hf_cache/` indicate model-based detection components backed by Hugging Face artifacts or similar downloaded models.
   - `heatmap.py` suggests explainability or localization output, generating visual overlays that are stored under `backend/data/heatmaps/`.
   - This subsystem is separate from UI concerns: the frontend likely only renders the resulting status and images/overlays produced by the backend.

6. **Persistence and local data stores**
   - `db.py` and `backend/data/aegis.db` show a local database-backed persistence layer, most likely SQLite for cases, users, audit records, and job metadata.
   - `backend/data/uploads/` stores submitted files, while `backend/data/heatmaps/` stores derived outputs.
   - The presence of cached model files means the backend has a local artifact store as part of runtime, not just a pure stateless API.

7. **Integration and external-service boundaries**
   - `auth.py`, `payments.py`, `email_router.py`, and `ironlabs_router.py` show explicit integration boundaries for identity, billing, notifications, and a domain-specific external service or partner system.
   - These modules are separated from the core analysis pipeline, which keeps business workflow distinct from infrastructure and third-party concerns.

8. **Auditability and trust model**
   - The frontend includes `HashChain.js` and an `AuditDetail` page, which strongly suggests a tamper-evident or chained audit log view for case history.
   - On the backend, the `audit` agent and audit-related routes likely record decision provenance, model outputs, and state transitions so a reviewer can reconstruct how a verdict was reached.

9. **User-facing workflow mapping**
   - The page set indicates a stateful review process rather than a generic dashboard app: `Upload` starts the case, `Processing` and `Verifying` represent intermediate states, and `Approved`, `Rejected`, and `Escalated` represent final decision branches.
   - `Dashboard` and `AgentCard`/`MetricTile` support operational visibility into the pipeline, not just end-user submission.

10. **Testing and validation surface**
   - Backend tests (`backend/tests/test_aegis_api.py`, `backend/tests/test_rxguard.py`) and the test report artifacts indicate the API and detection logic are tested as separate concerns.
   - The repo also includes dedicated testing notes (`auth_testing.md`, `image_testing.md`) and captured test outputs, implying the project treats auth and imaging behavior as important acceptance boundaries.

11. **How to draw the architecture**
   - The clearest diagram would place the React client on one side, the Python API server in the middle, and the local data/model stores plus external integrations on the other side.
   - Inside the backend, the most important internal box is the orchestrator driving the agent chain, with persistence, heatmap/model generation, auth/billing/email integrations, and audit logging branching around it.

Main entry points: [`backend/server.py`](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/server.py) (API server), [`backend/orchestrator.py`](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/orchestrator.py) (Orchestrator), [`backend/hf_detectors.py`](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/hf_detectors.py) (Detector models), [`frontend/src/App.js`](https://github.com/procoder1234556/aegis-imaging1/blob/main/frontend/src/App.js) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>react entry/routes<br/>[App.js]"]
  node_frontend_auth(("Auth boundary<br/>react context<br/>[AuthContext.js]"))
  node_frontend_guard{{"Protected route<br/>route guard<br/>[ProtectedRoute.js]"}}
  node_frontend_case_ui["Case pages<br/>workflow pages<br/>[Upload.js]"]
  node_frontend_audit_ui["Audit view<br/>review pages<br/>[AuditDetail.js]"]
end

subgraph group_backend["Backend"]
  node_backend_server["API server<br/>python entrypoint<br/>[server.py]"]
  node_backend_schemas["Schemas<br/>api contracts<br/>[schemas.py]"]
  node_backend_orchestrator{{"Orchestrator<br/>workflow coordinator<br/>[orchestrator.py]"}}
  node_backend_intake["Intake agent<br/>pipeline stage<br/>[intake.py]"]
  node_backend_clinical["Clinical agent<br/>pipeline stage<br/>[clinical.py]"]
  node_backend_forensics["Forensics agent<br/>pipeline stage<br/>[forensics.py]"]
  node_backend_audit["Audit agent<br/>pipeline stage<br/>[audit.py]"]
  node_backend_verdict["Verdict agent<br/>pipeline stage<br/>[verdict.py]"]
  node_backend_db[("Persistence<br/>sqlite db layer<br/>[db.py]")]
  node_backend_auth["Auth service<br/>identity integration<br/>[auth.py]"]
  node_backend_billing["Billing<br/>payment integration<br/>[payments.py]"]
  node_backend_email["Email router<br/>notification integration<br/>[email_router.py]"]
  node_backend_ironlabs["Partner router<br/>external integration<br/>[ironlabs_router.py]"]
  node_backend_hf["Detector models<br/>ml inference<br/>[hf_detectors.py]"]
  node_backend_heatmap["Heatmap output<br/>explainability<br/>[heatmap.py]"]
end

subgraph group_storage["Local data"]
  node_data_db[("Case DB<br/>sqlite data<br/>[aegis.db]")]
  node_data_uploads["Uploads<br/>file store"]
  node_data_heatmaps["Heatmaps<br/>artifact store"]
  node_data_cache["Model cache<br/>artifact store"]
end

node_frontend_app -->|"uses"| node_frontend_auth
node_frontend_app -->|"routes through"| node_frontend_guard
node_frontend_guard -->|"unlocks"| node_frontend_case_ui
node_frontend_app -->|"navigates to"| node_frontend_audit_ui
node_frontend_case_ui -->|"API calls"| node_backend_server
node_frontend_audit_ui -->|"API calls"| node_backend_server
node_backend_server -->|"validates"| node_backend_schemas
node_backend_server -->|"dispatches"| node_backend_orchestrator
node_backend_server -->|"authenticates"| node_backend_auth
node_backend_server -->|"exposes"| node_backend_billing
node_backend_server -->|"exposes"| node_backend_email
node_backend_server -->|"exposes"| node_backend_ironlabs
node_backend_orchestrator -->|"starts"| node_backend_intake
node_backend_orchestrator -->|"continues to"| node_backend_clinical
node_backend_orchestrator -->|"continues to"| node_backend_forensics
node_backend_orchestrator -->|"records"| node_backend_audit
node_backend_orchestrator -->|"finishes with"| node_backend_verdict
node_backend_intake -->|"reads/writes"| node_backend_db
node_backend_clinical -->|"uses"| node_backend_hf
node_backend_forensics -->|"uses"| node_backend_hf
node_backend_hf -->|"produces"| node_backend_heatmap
node_backend_heatmap -->|"stores"| node_data_heatmaps
node_backend_intake -->|"stores"| node_data_uploads
node_backend_db -->|"persists"| node_data_db
node_backend_hf -->|"loads"| node_data_cache

click node_frontend_app "https://github.com/procoder1234556/aegis-imaging1/blob/main/frontend/src/App.js"
click node_frontend_auth "https://github.com/procoder1234556/aegis-imaging1/blob/main/frontend/src/context/AuthContext.js"
click node_frontend_guard "https://github.com/procoder1234556/aegis-imaging1/blob/main/frontend/src/components/ProtectedRoute.js"
click node_frontend_case_ui "https://github.com/procoder1234556/aegis-imaging1/blob/main/frontend/src/pages/Upload.js"
click node_frontend_audit_ui "https://github.com/procoder1234556/aegis-imaging1/blob/main/frontend/src/pages/AuditDetail.js"
click node_backend_server "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/server.py"
click node_backend_schemas "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/schemas.py"
click node_backend_orchestrator "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/orchestrator.py"
click node_backend_intake "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/agents/intake.py"
click node_backend_clinical "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/agents/clinical.py"
click node_backend_forensics "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/agents/forensics.py"
click node_backend_audit "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/agents/audit.py"
click node_backend_verdict "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/agents/verdict.py"
click node_backend_db "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/db.py"
click node_backend_auth "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/auth.py"
click node_backend_billing "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/payments.py"
click node_backend_email "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/email_router.py"
click node_backend_ironlabs "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/ironlabs_router.py"
click node_backend_hf "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/hf_detectors.py"
click node_backend_heatmap "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/heatmap.py"
click node_data_db "https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/data/aegis.db"
click node_data_uploads "https://github.com/procoder1234556/aegis-imaging1/tree/main/backend/data/uploads"
click node_data_heatmaps "https://github.com/procoder1234556/aegis-imaging1/tree/main/backend/data/heatmaps"
click node_data_cache "https://github.com/procoder1234556/aegis-imaging1/tree/main/backend/data/hf_cache"

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_auth,node_frontend_guard,node_frontend_case_ui,node_frontend_audit_ui toneBlue
class node_backend_server,node_backend_schemas,node_backend_orchestrator,node_backend_intake,node_backend_clinical,node_backend_forensics,node_backend_audit,node_backend_verdict,node_backend_db,node_backend_auth,node_backend_billing,node_backend_email,node_backend_ironlabs,node_backend_hf,node_backend_heatmap toneAmber
class node_data_db,node_data_uploads,node_data_heatmaps,node_data_cache toneMint
```

## Components

### Frontend

React client and case workflow UI

- [App shell](https://github.com/procoder1234556/aegis-imaging1/blob/main/frontend/src/App.js): react entry/routes · Top-level client routing and layout · `frontend/src/App.js`
- [Auth boundary](https://github.com/procoder1234556/aegis-imaging1/blob/main/frontend/src/context/AuthContext.js): react context · Authenticated session state for the UI · `frontend/src/context/AuthContext.js`
- [Protected route](https://github.com/procoder1234556/aegis-imaging1/blob/main/frontend/src/components/ProtectedRoute.js): route guard · Blocks unauthenticated access to case screens · `frontend/src/components/ProtectedRoute.js`
- [Case pages](https://github.com/procoder1234556/aegis-imaging1/blob/main/frontend/src/pages/Upload.js): workflow pages · Upload, processing, verifying, and verdict screens · `frontend/src/pages/Upload.js`
- [Audit view](https://github.com/procoder1234556/aegis-imaging1/blob/main/frontend/src/pages/AuditDetail.js): review pages · Dashboard and tamper-evident case history display · `frontend/src/pages/AuditDetail.js`

### Backend

Python API, pipeline, and integrations

- [API server](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/server.py): python entrypoint · Service bootstrap and request entrypoint · `backend/server.py`
- [Schemas](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/schemas.py): api contracts · Shared request and response payload definitions · `backend/schemas.py`
- [Orchestrator](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/orchestrator.py): workflow coordinator · Coordinates the case processing pipeline · `backend/orchestrator.py`
- [Intake agent](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/agents/intake.py): pipeline stage · Normalizes uploads and case input · `backend/agents/intake.py`
- [Clinical agent](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/agents/clinical.py): pipeline stage · Evaluates medical and semantic relevance · `backend/agents/clinical.py`
- [Forensics agent](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/agents/forensics.py): pipeline stage · Checks integrity and abuse signals · `backend/agents/forensics.py`
- [Audit agent](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/agents/audit.py): pipeline stage · Records provenance and traceability · `backend/agents/audit.py`
- [Verdict agent](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/agents/verdict.py): pipeline stage · Produces final approved, rejected, or escalated outcome · `backend/agents/verdict.py`
- [Persistence](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/db.py): sqlite db layer · Case, user, and audit storage access · `backend/db.py`
- [Auth service](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/auth.py): identity integration · Backend authentication and session logic · `backend/auth.py`
- [Billing](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/payments.py): payment integration · Payment and subscription handling · `backend/payments.py`
- [Email router](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/email_router.py): notification integration · Outbound email and notification endpoints · `backend/email_router.py`
- [Partner router](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/ironlabs_router.py): external integration · Domain-specific partner or service boundary · `backend/ironlabs_router.py`
- [Detector models](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/hf_detectors.py): ml inference · Model-backed detection and classification components · `backend/hf_detectors.py`
- [Heatmap output](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/heatmap.py): explainability · Generates visual overlays and derived evidence · `backend/heatmap.py`

### Local data

Database, uploads, model cache, and derived outputs

- [Case DB](https://github.com/procoder1234556/aegis-imaging1/blob/main/backend/data/aegis.db): sqlite data · Runtime database file · `backend/data/aegis.db`
- [Uploads](https://github.com/procoder1234556/aegis-imaging1/tree/main/backend/data/uploads): file store · Submitted source files · `backend/data/uploads`
- [Heatmaps](https://github.com/procoder1234556/aegis-imaging1/tree/main/backend/data/heatmaps): artifact store · Rendered overlays and visual evidence · `backend/data/heatmaps`
- [Model cache](https://github.com/procoder1234556/aegis-imaging1/tree/main/backend/data/hf_cache): artifact store · Downloaded model artifacts and cache files · `backend/data/hf_cache`

## Connections

- App shell → Auth boundary: uses · App reads session state
- App shell → Protected route: routes through · Protected screens pass through auth gating
- Protected route → Case pages: unlocks · Case workflow pages after login
- App shell → Audit view: navigates to · Operational and audit views
- Case pages → API server: API calls · Uploads and case-state actions hit the backend
- Audit view → API server: API calls · Fetches audit and dashboard data
- API server → Schemas: validates · Uses shared request and response contracts
- API server → Orchestrator: dispatches · Routes case-processing work to the workflow coordinator
- API server → Auth service: authenticates · Handles identity and session enforcement
- API server → Billing: exposes · Payment and subscription endpoints
- API server → Email router: exposes · Notification endpoints
- API server → Partner router: exposes · Partner integration endpoints
- Orchestrator → Intake agent: starts · Initializes case normalization
- Orchestrator → Clinical agent: continues to · Runs medical and semantic analysis
- Orchestrator → Forensics agent: continues to · Checks integrity and abuse signals
- Orchestrator → Audit agent: records · Captures traceability during processing
- Orchestrator → Verdict agent: finishes with · Produces final case outcome
- Intake agent → Persistence: reads/writes · Persists case metadata and state
- Clinical agent → Detector models: uses · Runs model-backed detection
- Forensics agent → Detector models: uses · Consults detector outputs for abuse signals
- Detector models → Heatmap output: produces · Generates explainability artifacts
- Heatmap output → Heatmaps: stores · Writes rendered overlays
- Intake agent → Uploads: stores · Saves submitted files
- Persistence → Case DB: persists · Uses local SQLite-backed storage
- Detector models → Model cache: loads · Reads cached model artifacts