# nishithp2004/aegis architecture

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

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

## Overview

1. **Repo shape and primary boundary**
   - AEGIS is split into two independently containerized services: an **agent backend** under `agents/` and a **Streamlit dashboard** under `dashboard/`.
   - `docker-compose.yaml` is the top-level orchestration boundary that connects the UI to the grading API over the Docker network.

2. **Backend service: grading engine**
   - `agents/main.py` is the HTTP entry point, exposing the grading API with **FastAPI**.
   - The backend is responsible for receiving a grading request, invoking the AI-based grading workflow, and returning the final evaluation payload.

3. **Agent subsystem**
   - `agents/aegis_agent/agent.py` and `agents/aegis_agent/prompts.py` contain the core grading logic and prompt construction.
   - This is the internal “intelligence” layer: it likely assembles the rubric, student answer, and agent-specific prompts into a coordinated evaluation pipeline.

4. **Multi-agent evaluation model**
   - The README describes specialized roles such as **Arbiter, Scrutinizer, Validator, and Mentor**.
   - Architecturally, this implies the backend is not a single pass scorer; it performs cross-checking and reasoning across multiple agent perspectives before producing the final score and feedback.

5. **External model dependency**
   - The backend depends on **Google Cloud / Vertex AI** credentials (`GOOGLE_API_KEY`, `PROJECT_ID`).
   - This is the main external execution dependency: the grading logic is mediated through hosted AI models rather than local inference.

6. **Dashboard service: user-facing presentation**
   - `dashboard/app.py` is the Streamlit UI entry point.
   - It provides the interactive workflow for submitting assignments, viewing results, and navigating history/analytics tabs.

7. **Dashboard-to-backend communication**
   - `dashboard/api_client.py` is the integration boundary between the UI and the agent service.
   - The dashboard does not appear to grade directly; it packages user input, calls the backend API, and renders the returned grading output.

8. **Request types and input channels**
   - The system supports at least two input paths:
     - **Text submission**: rubric + student answer posted directly.
     - **OCR-based submission**: two PDF uploads, then text extraction/proc essing before grading.
   - This means the dashboard is the ingestion layer, while the backend consumes a normalized grading prompt.

9. **Persistence and analytics**
   - The README mentions **history and analytics**, with optional **Redis** settings in Streamlit secrets.
   - No dedicated database service is present in the visible tree, so persistence is either optional, external, or lightweight rather than a core repo-managed datastore.

10. **Deployment and runtime packaging**
    - Each service has its own `Dockerfile` and dependency manifest (`requirements.txt`; the agents package also has `pyproject.toml`).
    - `docker-compose.yaml` starts the backend on **port 8000** and the dashboard on **port 8501**, which is the main runtime topology to capture in an architecture diagram.

11. **End-to-end data flow**
    - User submits rubric/answer in Streamlit → dashboard prepares request via `api_client.py` → FastAPI backend receives the prompt → multi-agent grading logic in `aegis_agent` evaluates and cross-checks → final score/feedback is returned to the dashboard → results are displayed and optionally stored for history/analytics.

12. **Useful diagram boundaries**
    - For a diagram, the clearest boxes are: **User/UI**, **Streamlit Dashboard**, **FastAPI Agent Service**, **Multi-agent Grading Core**, and **External AI/Vertex AI**.
    - The main arrows are: user input into dashboard, API call from dashboard to agents, and model-backed evaluation from agents to Google AI services.

Main entry points: [`dashboard/app.py`](https://github.com/nishithp2004/aegis/blob/main/dashboard/app.py) (Dashboard app), [`agents/aegis_agent/agent.py`](https://github.com/nishithp2004/aegis/blob/main/agents/aegis_agent/agent.py) (Agent core), [`agents/main.py`](https://github.com/nishithp2004/aegis/blob/main/agents/main.py) (Agent API), [`docker-compose.yaml`](https://github.com/nishithp2004/aegis/blob/main/docker-compose.yaml) (Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime services"]
  node_docker_compose["Compose<br/>orchestration"]
end

subgraph group_backend["Agent backend"]
  node_agents_main["Agent API<br/>fastapi entrypoint<br/>[main.py]"]
  node_agent_core["Agent core<br/>grading coordinator<br/>[agent.py]"]
  node_prompts["Prompts<br/>prompt builder<br/>[prompts.py]"]
  node_multi_agent{{"Multi-agent eval<br/>reasoning pipeline"}}
  node_vertex_ai{{"Vertex AI<br/>hosted model dependency"}}
  node_google_creds["Google creds<br/>runtime config"]
  node_agents_docker["Agent image<br/>container packaging"]
  node_agents_pkg["Agent package<br/>python package<br/>[pyproject.toml]"]
end

subgraph group_frontend["Dashboard"]
  node_dashboard_app["Dashboard app<br/>streamlit entrypoint<br/>[app.py]"]
  node_dashboard_api["API client<br/>integration layer<br/>[api_client.py]"]
  node_grading_request["Grading input<br/>normalized payload"]
  node_ocr_flow["OCR flow<br/>document processing"]
  node_history_analytics[("History<br/>results storage")]
  node_dashboard_docker["Dashboard image<br/>container packaging"]
  node_dashboard_deps["UI deps<br/>python dependencies<br/>[requirements.txt]"]
end

node_docker_compose -->|"builds"| node_dashboard_docker
node_docker_compose -->|"builds"| node_agents_docker
node_dashboard_docker -->|"runs"| node_dashboard_app
node_dashboard_app -->|"uses"| node_dashboard_api
node_dashboard_api -->|"packages"| node_grading_request
node_dashboard_app -->|"uploads"| node_ocr_flow
node_ocr_flow -->|"extracts"| node_grading_request
node_grading_request -->|"POSTs to"| node_agents_main
node_agents_docker -->|"runs"| node_agents_main
node_agents_main -->|"dispatches"| node_agent_core
node_agent_core -->|"builds"| node_prompts
node_agent_core -->|"orchestrates"| node_multi_agent
node_multi_agent -->|"calls"| node_vertex_ai
node_google_creds -->|"authenticates"| node_vertex_ai
node_agents_pkg -.->|"packages"| node_agents_main
node_dashboard_deps -.->|"packages"| node_dashboard_app
node_agent_core -->|"returns"| node_history_analytics
node_dashboard_app -->|"displays"| node_history_analytics

click node_docker_compose "https://github.com/nishithp2004/aegis/blob/main/docker-compose.yaml"
click node_dashboard_app "https://github.com/nishithp2004/aegis/blob/main/dashboard/app.py"
click node_dashboard_api "https://github.com/nishithp2004/aegis/blob/main/dashboard/api_client.py"
click node_agents_main "https://github.com/nishithp2004/aegis/blob/main/agents/main.py"
click node_agent_core "https://github.com/nishithp2004/aegis/blob/main/agents/aegis_agent/agent.py"
click node_prompts "https://github.com/nishithp2004/aegis/blob/main/agents/aegis_agent/prompts.py"
click node_dashboard_docker "https://github.com/nishithp2004/aegis/tree/main/dashboard/Dockerfile"
click node_agents_docker "https://github.com/nishithp2004/aegis/tree/main/agents/Dockerfile"
click node_agents_pkg "https://github.com/nishithp2004/aegis/blob/main/agents/pyproject.toml"
click node_dashboard_deps "https://github.com/nishithp2004/aegis/blob/main/dashboard/requirements.txt"

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_docker_compose toneBlue
class node_agents_main,node_agent_core,node_prompts,node_multi_agent,node_vertex_ai,node_google_creds,node_agents_docker,node_agents_pkg toneAmber
class node_dashboard_app,node_dashboard_api,node_grading_request,node_ocr_flow,node_history_analytics,node_dashboard_docker,node_dashboard_deps toneMint
```

## Components

### Runtime services

Containerized services and orchestration at the repository boundary

- [Compose](https://github.com/nishithp2004/aegis/blob/main/docker-compose.yaml): orchestration · Top-level container orchestration connecting dashboard and backend · `docker-compose.yaml`

### Agent backend

FastAPI grading service and AI-driven evaluation core

- [Agent API](https://github.com/nishithp2004/aegis/blob/main/agents/main.py): fastapi entrypoint · HTTP entry point for the grading backend · `agents/main.py`
- [Agent core](https://github.com/nishithp2004/aegis/blob/main/agents/aegis_agent/agent.py): grading coordinator · Coordinates rubric-aware grading and orchestrates the evaluation workflow · `agents/aegis_agent/agent.py`
- [Prompts](https://github.com/nishithp2004/aegis/blob/main/agents/aegis_agent/prompts.py): prompt builder · Constructs prompts and role instructions for the grading pipeline · `agents/aegis_agent/prompts.py`
- **Multi-agent eval**: reasoning pipeline · Cross-checking roles such as arbiter, scrutinizer, validator, and mentor
- **Vertex AI**: hosted model dependency · External AI model backend used for grading and feedback generation
- **Google creds**: runtime config · API key and project credentials required by the backend
- [Agent image](https://github.com/nishithp2004/aegis/tree/main/agents/Dockerfile): container packaging · Container build for the grading backend · `agents/Dockerfile`
- [Agent package](https://github.com/nishithp2004/aegis/blob/main/agents/pyproject.toml): python package · Backend packaging and dependency definition · `agents/pyproject.toml`

### Dashboard

Streamlit UI and request packaging layer

- [Dashboard app](https://github.com/nishithp2004/aegis/blob/main/dashboard/app.py): streamlit entrypoint · Streamlit user interface for submissions, results, and history · `dashboard/app.py`
- [API client](https://github.com/nishithp2004/aegis/blob/main/dashboard/api_client.py): integration layer · Packages dashboard input and calls the grading service · `dashboard/api_client.py`
- **Grading input**: normalized payload · Rubric and student answer after UI packaging and preprocessing
- **OCR flow**: document processing · PDF upload and text extraction path used for scanned submissions
- **History**: results storage · Optional history and analytics surfaced in the dashboard
- [Dashboard image](https://github.com/nishithp2004/aegis/tree/main/dashboard/Dockerfile): container packaging · Container build for the Streamlit service · `dashboard/Dockerfile`
- [UI deps](https://github.com/nishithp2004/aegis/blob/main/dashboard/requirements.txt): python dependencies · Streamlit service dependency manifest · `dashboard/requirements.txt`

## Connections

- Compose → Dashboard image: builds · Compose starts the dashboard container
- Compose → Agent image: builds · Compose starts the grading backend container
- Dashboard image → Dashboard app: runs · Dashboard image launches the Streamlit app
- Dashboard app → API client: uses · UI delegates backend communication to the API client
- API client → Grading input: packages · Converts user input into a normalized grading payload
- Dashboard app → OCR flow: uploads · Supports PDF-based submission and text extraction
- OCR flow → Grading input: extracts · Normalizes OCR output into text for grading
- Grading input → Agent API: POSTs to · Dashboard sends the grading request to the backend API
- Agent image → Agent API: runs · Backend image launches the FastAPI service
- Agent API → Agent core: dispatches · HTTP entry point hands requests to the grading coordinator
- Agent core → Prompts: builds · Core logic assembles role-specific prompts
- Agent core → Multi-agent eval: orchestrates · Coordinates cross-checking and role-based evaluation
- Multi-agent eval → Vertex AI: calls · Evaluation uses hosted AI models
- Google creds → Vertex AI: authenticates · Credentials configure access to the model service
- Agent package → Agent API: packages · Defines backend runtime and dependencies
- UI deps → Dashboard app: packages · Defines dashboard runtime dependencies
- Agent core → History: returns · Grading results can feed dashboard history and analytics
- Dashboard app → History: displays · Dashboard surfaces prior results and analytics views
