How procoder1234556/aegis-imaging1 works
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: server.py API server · orchestrator.py Orchestrator · hf_detectors.py Detector models · App.js App shell
Components 24
Frontend
React client and case workflow UI
- App shell · Top-level client routing and layout
frontend/src/App.js - Auth boundary · Authenticated session state for the UI
frontend/src/context/AuthContext.js - Protected route · Blocks unauthenticated access to case screens
frontend/src/components/ProtectedRoute.js - Case pages · Upload, processing, verifying, and verdict screens
frontend/src/pages/Upload.js - Audit view · Dashboard and tamper-evident case history display
frontend/src/pages/AuditDetail.js
Backend
Python API, pipeline, and integrations
- API server · Service bootstrap and request entrypoint
backend/server.py - Schemas · Shared request and response payload definitions
backend/schemas.py - Orchestrator · Coordinates the case processing pipeline
backend/orchestrator.py - Intake agent · Normalizes uploads and case input
backend/agents/intake.py - Clinical agent · Evaluates medical and semantic relevance
backend/agents/clinical.py - Forensics agent · Checks integrity and abuse signals
backend/agents/forensics.py - Audit agent · Records provenance and traceability
backend/agents/audit.py - Verdict agent · Produces final approved, rejected, or escalated outcome
backend/agents/verdict.py - Persistence · Case, user, and audit storage access
backend/db.py - Auth service · Backend authentication and session logic
backend/auth.py - Billing · Payment and subscription handling
backend/payments.py - Email router · Outbound email and notification endpoints
backend/email_router.py - Partner router · Domain-specific partner or service boundary
backend/ironlabs_router.py - Detector models · Model-backed detection and classification components
backend/hf_detectors.py - Heatmap output · Generates visual overlays and derived evidence
backend/heatmap.py
Local data
Database, uploads, model cache, and derived outputs
- Case DB · Runtime database file
backend/data/aegis.db - Uploads · Submitted source files
backend/data/uploads - Heatmaps · Rendered overlays and visual evidence
backend/data/heatmaps - Model cache · Downloaded model artifacts and cache files
backend/data/hf_cache
Connections 25
- 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