# reemasaif/ndi-ai-agent-capstone-project architecture

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

- Interactive diagram: https://gitdiagram.com/reemasaif/ndi-ai-agent-capstone-project
- Repository: https://github.com/reemasaif/ndi-ai-agent-capstone-project

## Overview

1. **What this repo is**
   - NDI-Sentinel is a local, document-driven governance and compliance system for monitoring NDMO / NDI alignment.
   - The repository combines policy retrieval, compliance analysis, scoring, report generation, and a dashboard for visibility.

2. **Core architecture pattern**
   - The system is organized as a pipeline around three kinds of artifacts:  
     policy/knowledge documents, operational data, and generated compliance outputs.
   - Most components appear to run as offline or batch jobs rather than a continuously hosted cloud service.

3. **Knowledge and retrieval layer**
   - `RAG/Vectors/db_setup.py` and the persisted `chroma_db/` folder indicate a Chroma-based vector store.
   - Policy PDFs in `src/knowledge_base/` and `data/` are the main retrieval corpus.
   - `RAG/Retrieval/query_agent.py` is the retrieval entry point that likely turns policy questions or compliance checks into vector search queries.

4. **Compliance analysis layer**
   - `src/compliance_agent.py` is the central compliance reasoning component.
   - It likely combines retrieved policy context with source data from files and/or the database to detect gaps, classify records, or produce evidence for compliance evaluation.
   - The presence of `data/security_document.txt`, `data/top_secret_document.txt`, `data/medical_report.txt`, and `data/public_announcement.txt` suggests the agent evaluates sensitivity or policy adherence across mixed document types.

5. **Scoring subsystem**
   - The `scoring/` package is a separate evaluation pipeline for turning findings into numeric or categorical maturity/compliance scores.
   - `scoring/scoring_engine.py` appears to hold the scoring rules.
   - `scoring/score_db.py` and `scoring/score_export.py` connect scoring results to storage and export, while `scoring/main_execution.py` likely orchestrates the full scoring run.

6. **Relational database boundary**
   - The `database/` directory contains schema creation scripts, connection handling, and mock data generation.
   - This is the structured-data side of the system, distinct from the vector store used for policy retrieval.
   - `database/test_db_connection.py` indicates the database is a first-class dependency and likely used to validate environment setup before analysis.

7. **Reporting layer**
   - The `reporting/` package converts analysis results into human-readable artifacts, especially PDFs.
   - `reporting/pdf_builder.py`, `reporting/layouts.py`, and `reporting/font.py` suggest custom document formatting, likely including Arabic-aware output.
   - `reporting/run_report.py` is the orchestration entry point for generating final deliverables.

8. **Strategic advisor outputs**
   - `Strategic Advisor/advisor_agent.py` appears to be a higher-level synthesis agent.
   - Its outputs in `Strategic Advisor/Outputs/` include `governance_report.txt` and `final_report.txt`, which likely summarize technical findings into executive guidance.
   - This is a distinct layer from raw compliance scoring: it turns evidence into strategic recommendations.

9. **Dashboard / presentation boundary**
   - `dashboard/app.py` is the user-facing app for viewing results.
   - It likely reads from generated outputs, the database, or report artifacts rather than recomputing compliance from scratch.
   - This keeps presentation separate from analysis and makes the dashboard a consumer of pipeline outputs.

10. **Data flow across the system**
   - Source documents and records enter through the `data/`, `src/knowledge_base/`, and `database/` layers.
   - Policies are embedded into Chroma for retrieval.
   - The compliance agent queries retrieved policy context, scoring converts findings into metrics, and reporting produces PDFs/JSON/text summaries.
   - The dashboard and strategic advisor consume those derived artifacts.

11. **Artifacts and persistence**
   - The repo includes generated outputs in `output/`, `outputs/`, and `Strategic Advisor/Outputs/`, showing the system persists analysis results as files.
   - `chroma_db/` is a durable local index for semantic retrieval.
   - This makes the project reproducible without requiring a remote service dependency.

12. **Important technology signals**
   - The stack is Python-based, with Chroma for vector search, a relational database layer, PDF generation tooling, and file-based reporting.
   - Arabic document names and Arabic report outputs indicate multilingual compliance support is an architectural requirement, not just a content detail.

13. **How to draw the architecture**
   - Model it as three major zones:  
     **Data/Knowledge sources** → **Analysis and scoring services** → **Outputs and visualization**.
   - Place the vector database beside the policy corpus, the relational database beside operational records, and connect both into the compliance/scoring pipeline.
   - Treat the dashboard and executive advisor as downstream consumers of generated findings.

Main entry points: [`src/compliance_agent.py`](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/src/compliance_agent.py) (Compliance agent), [`scoring/score_export.py`](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/scoring/score_export.py) (Score export), [`scoring/scoring_engine.py`](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/scoring/scoring_engine.py) (Scoring engine), [`database`](https://github.com/reemasaif/ndi-ai-agent-capstone-project/tree/main/database) (Database layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sources["Data & knowledge"]
  node_knowledge_corpus["Policy corpus<br/>document sources"]
  node_operational_data["Operational data<br/>case records"]
  node_vector_store[("Chroma store<br/>vector index")]
  node_db_schema[("Database layer<br/>relational data")]
  node_db_connection["DB connection<br/>access layer<br/>[connection.py]"]
end

subgraph group_analysis["Retrieval & compliance"]
  node_retrieval_agent["Query agent<br/>retrieval<br/>[query_agent.py]"]
  node_vector_setup["Vector setup<br/>index builder<br/>[db_setup.py]"]
  node_compliance_agent["Compliance agent<br/>reasoning"]
end

subgraph group_output["Scoring & reports"]
  node_scoring_engine["Scoring engine<br/>rules engine<br/>[scoring_engine.py]"]
  node_score_db[("Score store<br/>result persistence<br/>[score_db.py]")]
  node_score_export["Score export<br/>[score_export.py]"]
  node_scoring_orchestrator["Scoring run<br/>pipeline<br/>[main_execution.py]"]
  node_report_builder["PDF builder<br/>reporting<br/>[pdf_builder.py]"]
  node_report_layouts["Layouts<br/>formatting<br/>[layouts.py]"]
  node_report_runner["Report runner<br/>orchestration<br/>[run_report.py]"]
end

subgraph group_presentation["Advisor & dashboard"]
  node_advisor_agent["Advisor agent<br/>synthesis<br/>[advisor_agent.py]"]
  node_dashboard_app["Dashboard<br/>ui<br/>[app.py]"]
  node_advisor_outputs["Advisor outputs<br/>reports"]
end

node_knowledge_corpus -->|"embed"| node_vector_setup
node_vector_setup -->|"persist"| node_vector_store
node_operational_data -->|"load"| node_db_schema
node_db_connection -->|"connect"| node_db_schema
node_vector_store -->|"search"| node_retrieval_agent
node_retrieval_agent -->|"context"| node_compliance_agent
node_operational_data -->|"records"| node_compliance_agent
node_db_schema -->|"structured data"| node_compliance_agent
node_compliance_agent -->|"findings"| node_scoring_engine
node_scoring_engine -->|"store"| node_score_db
node_score_db -->|"export"| node_score_export
node_scoring_engine -->|"run"| node_scoring_orchestrator
node_scoring_orchestrator -->|"emit"| node_score_export
node_compliance_agent -->|"evidence"| node_report_builder
node_report_layouts -->|"format"| node_report_builder
node_report_builder -->|"generate"| node_report_runner
node_score_export -->|"inputs"| node_report_runner
node_report_runner -->|"write"| node_advisor_outputs
node_compliance_agent -->|"synthesize"| node_advisor_agent
node_advisor_agent -->|"publish"| node_advisor_outputs
node_score_export -->|"view"| node_dashboard_app
node_advisor_outputs -->|"consume"| node_dashboard_app

click node_knowledge_corpus "https://github.com/reemasaif/ndi-ai-agent-capstone-project/tree/main/src/knowledge_base"
click node_operational_data "https://github.com/reemasaif/ndi-ai-agent-capstone-project/tree/main/data"
click node_vector_store "https://github.com/reemasaif/ndi-ai-agent-capstone-project/tree/main/chroma_db"
click node_db_schema "https://github.com/reemasaif/ndi-ai-agent-capstone-project/tree/main/database"
click node_db_connection "https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/database/connection.py"
click node_retrieval_agent "https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/RAG/Retrieval/query_agent.py"
click node_vector_setup "https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/RAG/Vectors/db_setup.py"
click node_compliance_agent "https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/src/compliance_agent.py"
click node_scoring_engine "https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/scoring/scoring_engine.py"
click node_score_db "https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/scoring/score_db.py"
click node_score_export "https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/scoring/score_export.py"
click node_scoring_orchestrator "https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/scoring/main_execution.py"
click node_report_builder "https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/reporting/pdf_builder.py"
click node_report_layouts "https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/reporting/layouts.py"
click node_report_runner "https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/reporting/run_report.py"
click node_advisor_agent "https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/Strategic Advisor/advisor_agent.py"
click node_dashboard_app "https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/dashboard/app.py"
click node_advisor_outputs "https://github.com/reemasaif/ndi-ai-agent-capstone-project/tree/main/Strategic Advisor/Outputs"

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_knowledge_corpus,node_operational_data,node_vector_store,node_db_schema,node_db_connection toneBlue
class node_retrieval_agent,node_vector_setup,node_compliance_agent toneAmber
class node_scoring_engine,node_score_db,node_score_export,node_scoring_orchestrator,node_report_builder,node_report_layouts,node_report_runner toneMint
class node_advisor_agent,node_dashboard_app,node_advisor_outputs toneRose
```

## Components

### Data & knowledge

Policy documents, operational records, and persisted semantic index.

- [Policy corpus](https://github.com/reemasaif/ndi-ai-agent-capstone-project/tree/main/src/knowledge_base): document sources · PDF policy and guidance documents used as retrieval knowledge. · `src/knowledge_base`
- [Operational data](https://github.com/reemasaif/ndi-ai-agent-capstone-project/tree/main/data): case records · Mixed sensitive and public sample records used for compliance evaluation. · `data`
- [Chroma store](https://github.com/reemasaif/ndi-ai-agent-capstone-project/tree/main/chroma_db): vector index · Persistent local embedding store for policy retrieval. · `chroma_db`
- [Database layer](https://github.com/reemasaif/ndi-ai-agent-capstone-project/tree/main/database): relational data · Structured database setup, schema, and seeded records. · `database`
- [DB connection](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/database/connection.py): access layer · Database connection and environment validation boundary. · `database/connection.py`

### Retrieval & compliance

Vector retrieval and compliance reasoning over retrieved policy context.

- [Query agent](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/RAG/Retrieval/query_agent.py): retrieval · Turns policy questions into vector search and retrieved context. · `RAG/Retrieval/query_agent.py`
- [Vector setup](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/RAG/Vectors/db_setup.py): index builder · Creates and initializes the Chroma vector database. · `RAG/Vectors/db_setup.py`
- [Compliance agent](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/src/compliance_agent.py): reasoning · Core compliance analysis component combining retrieved policy with source records. · `src/compliance_agent.py`

### Scoring & reports

Scoring, exports, and document generation from analysis results.

- [Scoring engine](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/scoring/scoring_engine.py): rules engine · Converts compliance findings into scores and maturity signals. · `scoring/scoring_engine.py`
- [Score store](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/scoring/score_db.py): result persistence · Stores scoring outputs for reuse and export. · `scoring/score_db.py`
- [Score export](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/scoring/score_export.py): export · Formats score results into exportable artifacts. · `scoring/score_export.py`
- [Scoring run](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/scoring/main_execution.py): pipeline · Coordinates the full scoring execution flow. · `scoring/main_execution.py`
- [PDF builder](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/reporting/pdf_builder.py): reporting · Builds formatted compliance and governance PDFs. · `reporting/pdf_builder.py`
- [Layouts](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/reporting/layouts.py): formatting · Document layout and rendering rules for report generation. · `reporting/layouts.py`
- [Report runner](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/reporting/run_report.py): orchestration · Runs the reporting pipeline end to end. · `reporting/run_report.py`

### Advisor & dashboard

Downstream consumers for executive synthesis and viewing.

- [Advisor agent](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/HEAD/Strategic%20Advisor/advisor_agent.py): synthesis · Produces executive governance guidance from analysis outputs. · `Strategic Advisor/advisor_agent.py`
- [Dashboard](https://github.com/reemasaif/ndi-ai-agent-capstone-project/blob/main/dashboard/app.py): ui · User-facing app for viewing results and outputs. · `dashboard/app.py`
- [Advisor outputs](https://github.com/reemasaif/ndi-ai-agent-capstone-project/tree/HEAD/Strategic%20Advisor/Outputs): reports · Persisted strategic summaries and final governance reports. · `Strategic Advisor/Outputs`

## Connections

- Policy corpus → Vector setup: embed · Policy PDFs are indexed into the local vector store.
- Vector setup → Chroma store: persist · Vector setup writes the durable Chroma index.
- Operational data → Database layer: load · Operational records are loaded into the relational layer.
- DB connection → Database layer: connect · Connection module mediates access to structured data.
- Chroma store → Query agent: search · Retriever queries the semantic index for relevant policy context.
- Query agent → Compliance agent: context · Retrieved policy evidence feeds compliance reasoning.
- Operational data → Compliance agent: records · Source documents and records are evaluated by the compliance agent.
- Database layer → Compliance agent: structured data · Compliance analysis can draw on relational records and mock data.
- Compliance agent → Scoring engine: findings · Compliance findings are translated into scores.
- Scoring engine → Score store: store · Computed scores are persisted for downstream use.
- Score store → Score export: export · Stored results are formatted for external consumption.
- Scoring engine → Scoring run: run · Main execution coordinates scoring rules and outputs.
- Scoring run → Score export: emit · Pipeline emits exportable scoring artifacts.
- Compliance agent → PDF builder: evidence · Analysis results provide the basis for generated reports.
- Layouts → PDF builder: format · Layout rules shape report presentation.
- PDF builder → Report runner: generate · Builder is invoked by the reporting orchestrator.
- Score export → Report runner: inputs · Reporting consumes exported score artifacts.
- Report runner → Advisor outputs: write · Reporting writes final deliverables and summaries.
- Compliance agent → Advisor agent: synthesize · Strategic advisor consumes compliance findings for executive guidance.
- Advisor agent → Advisor outputs: publish · Advisor writes governance and final reports.
- Score export → Dashboard: view · Dashboard reads prepared outputs for presentation.
- Advisor outputs → Dashboard: consume · Dashboard can surface strategic summaries and final reports.
