# aakarsh-kumar/binary-trace architecture

> Architecture diagram of the GitHub repository aakarsh-kumar/binary-trace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aakarsh-kumar/binary-trace
- Repository: https://github.com/aakarsh-kumar/binary-trace

## Overview

Compliance Review is a local-first system for reviewing student submissions against capability-specific compliance skills, with evidence verification and a Streamlit dashboard. The main workflow accepts a submission, extracts prose or repository content, selects applicable skills, runs deterministic and (when enabled) model-based checks, verifies flagged evidence, and records results for review. Supporting branches manage skill retrieval, persistent audit data, and metrics. The graph follows documented behavior and source-index references; unsampled implementation details and dashboard wiring are not assumed.

Main entry points: [`src/compliance_review/harness/orchestrator.py`](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/harness/orchestrator.py) (Review Orchestrator), [`src/compliance_review/harness/k_run.py`](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/harness/k_run.py) (K-Run Checks), [`src/compliance_review/ingestion/orchestrator.py`](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/ingestion/orchestrator.py) (Ingestion Orchestrator), [`src/compliance_review/db/repository.py`](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/db/repository.py) (Review Repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_dashboard["Dashboard<br/>[app.py]"]
  node_upload["Upload Handler<br/>[upload_handler.py]"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_ingest["Submission Ingestion"]
  node_ingest_flow["Ingestion Orchestrator<br/>[orchestrator.py]"]
  node_document_readers["Document Readers"]
  node_repo_reader["Repository Reader<br/>[repo.py]"]
end

subgraph group_review["Review Pipeline"]
  node_review_flow["Review Orchestrator<br/>[orchestrator.py]"]
  node_krun["K-Run Checks<br/>[k_run.py]"]
  node_det_code["Code Checks<br/>[code.py]"]
  node_det_disclosure["Disclosure Checks<br/>[disclosure.py]"]
  node_other_checks["Other Checks"]
  node_evidence["Evidence Verifier<br/>[verifier.py]"]
  node_model_client["Model Client<br/>[qwen_client.py]"]
end

subgraph group_skills["Skills and Retrieval"]
  node_skill_loader["Skill Loader<br/>[loader.py]"]
  node_cap_gate["Capability Gate<br/>[capability_gate.py]"]
  node_skill_selector["Skill Selector<br/>[selector.py]"]
  node_vector_index["Vector Index<br/>[vector_index.py]"]
end

subgraph group_data["Persistence and Insights"]
  node_queries["Dashboard Queries<br/>[queries.py]"]
  node_repository["Review Repository<br/>[repository.py]"]
  node_tables[("Database Tables<br/>[tables.py]")]
  node_db_engine["Database Engine<br/>[engine.py]"]
  node_metrics["Metrics<br/>[compute.py]"]
end

node_submitter(("Reviewer"))

node_submitter -->|"uploads submission"| node_dashboard
node_dashboard -->|"handles upload"| node_upload
node_dashboard -->|"loads submissions"| node_queries
node_upload -.->|"invokes ingest callback"| node_ingest_flow
node_upload -.->|"invokes review callback"| node_review_flow
node_cli -->|"calls"| node_ingest_flow
node_cli -->|"calls"| node_review_flow
node_cli -->|"computes metrics"| node_metrics
node_ingest_flow -->|"dispatches formats"| node_document_readers
node_ingest_flow -->|"reads repository"| node_repo_reader
node_ingest_flow -->|"creates submission"| node_repository
node_review_flow -->|"gates capabilities"| node_cap_gate
node_review_flow -->|"selects versions"| node_skill_selector
node_review_flow -->|"loads skill"| node_skill_loader
node_review_flow -->|"runs checks"| node_krun
node_review_flow -->|"verifies flags"| node_evidence
node_review_flow -->|"persists results"| node_repository
node_skill_selector -.->|"retrieves versions"| node_vector_index
node_krun -->|"runs code checks"| node_det_code
node_krun -->|"runs disclosure checks"| node_det_disclosure
node_krun -->|"runs other checks"| node_other_checks
node_krun -->|"normalizes evidence"| node_evidence
node_krun -.->|"requests inference"| node_model_client
node_queries -->|"queries records"| node_repository
node_repository -->|"opens connections"| node_db_engine
node_repository -->|"queries and writes"| node_tables
node_metrics -->|"reads database"| node_db_engine
node_metrics -->|"reads review data"| node_tables
node_metrics -->|"uses verification"| node_evidence

click node_dashboard "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/dashboard/app.py"
click node_upload "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/dashboard/upload_handler.py"
click node_cli "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/cli.py"
click node_ingest_flow "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/ingestion/orchestrator.py"
click node_document_readers "https://github.com/aakarsh-kumar/binary-trace/tree/main/src/compliance_review/ingestion"
click node_repo_reader "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/ingestion/repo.py"
click node_review_flow "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/harness/orchestrator.py"
click node_krun "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/harness/k_run.py"
click node_det_code "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/checks/deterministic/code.py"
click node_det_disclosure "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/checks/deterministic/disclosure.py"
click node_other_checks "https://github.com/aakarsh-kumar/binary-trace/tree/main/src/compliance_review/checks"
click node_evidence "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/evidence/verifier.py"
click node_model_client "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/model/qwen_client.py"
click node_skill_loader "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/skills/loader.py"
click node_cap_gate "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/retrieval/capability_gate.py"
click node_skill_selector "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/retrieval/selector.py"
click node_vector_index "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/retrieval/vector_index.py"
click node_queries "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/dashboard/queries.py"
click node_repository "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/db/repository.py"
click node_tables "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/db/tables.py"
click node_db_engine "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/db/engine.py"
click node_metrics "https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/metrics/compute.py"

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_dashboard,node_upload,node_cli,node_submitter toneBlue
class node_ingest_flow,node_document_readers,node_repo_reader toneAmber
class node_review_flow,node_krun,node_det_code,node_det_disclosure,node_other_checks,node_evidence,node_model_client toneMint
class node_skill_loader,node_cap_gate,node_skill_selector,node_vector_index toneRose
class node_queries,node_repository,node_tables,node_db_engine,node_metrics toneIndigo
```

## Components

### User Entry

- [Dashboard](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/dashboard/app.py): `src/compliance_review/dashboard/app.py`
- [Upload Handler](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/dashboard/upload_handler.py): `src/compliance_review/dashboard/upload_handler.py`
- [CLI](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/cli.py): `src/compliance_review/cli.py`

### Submission Ingestion

- [Ingestion Orchestrator](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/ingestion/orchestrator.py): `src/compliance_review/ingestion/orchestrator.py`
- [Document Readers](https://github.com/aakarsh-kumar/binary-trace/tree/main/src/compliance_review/ingestion): `src/compliance_review/ingestion`
- [Repository Reader](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/ingestion/repo.py): `src/compliance_review/ingestion/repo.py`

### Review Pipeline

- [Review Orchestrator](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/harness/orchestrator.py): `src/compliance_review/harness/orchestrator.py`
- [K-Run Checks](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/harness/k_run.py): `src/compliance_review/harness/k_run.py`
- [Code Checks](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/checks/deterministic/code.py): `src/compliance_review/checks/deterministic/code.py`
- [Disclosure Checks](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/checks/deterministic/disclosure.py): `src/compliance_review/checks/deterministic/disclosure.py`
- [Other Checks](https://github.com/aakarsh-kumar/binary-trace/tree/main/src/compliance_review/checks): `src/compliance_review/checks`
- [Evidence Verifier](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/evidence/verifier.py): `src/compliance_review/evidence/verifier.py`
- [Model Client](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/model/qwen_client.py): `src/compliance_review/model/qwen_client.py`

### Skills and Retrieval

- [Skill Loader](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/skills/loader.py): `src/compliance_review/skills/loader.py`
- [Capability Gate](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/retrieval/capability_gate.py): `src/compliance_review/retrieval/capability_gate.py`
- [Skill Selector](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/retrieval/selector.py): `src/compliance_review/retrieval/selector.py`
- [Vector Index](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/retrieval/vector_index.py): `src/compliance_review/retrieval/vector_index.py`

### Persistence and Insights

- [Dashboard Queries](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/dashboard/queries.py): `src/compliance_review/dashboard/queries.py`
- [Review Repository](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/db/repository.py): `src/compliance_review/db/repository.py`
- [Database Tables](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/db/tables.py): `src/compliance_review/db/tables.py`
- [Database Engine](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/db/engine.py): `src/compliance_review/db/engine.py`
- [Metrics](https://github.com/aakarsh-kumar/binary-trace/blob/main/src/compliance_review/metrics/compute.py): `src/compliance_review/metrics/compute.py`

### Other components

- **Reviewer**

## Connections

- Reviewer → Dashboard: uploads submission (evidence: `src/compliance_review/dashboard/app.py`)
- Dashboard → Upload Handler: handles upload (evidence: `src/compliance_review/dashboard/app.py`)
- Dashboard → Dashboard Queries: loads submissions (evidence: `src/compliance_review/dashboard/app.py`)
- Upload Handler → Ingestion Orchestrator: invokes ingest callback
- Upload Handler → Review Orchestrator: invokes review callback
- CLI → Ingestion Orchestrator: calls (evidence: `src/compliance_review/cli.py`)
- CLI → Review Orchestrator: calls (evidence: `src/compliance_review/cli.py`)
- CLI → Metrics: computes metrics (evidence: `src/compliance_review/cli.py`)
- Ingestion Orchestrator → Document Readers: dispatches formats (evidence: `src/compliance_review/ingestion/orchestrator.py`)
- Ingestion Orchestrator → Repository Reader: reads repository (evidence: `src/compliance_review/ingestion/orchestrator.py`)
- Ingestion Orchestrator → Review Repository: creates submission (evidence: `src/compliance_review/ingestion/orchestrator.py`)
- Review Orchestrator → Capability Gate: gates capabilities (evidence: `src/compliance_review/harness/orchestrator.py`)
- Review Orchestrator → Skill Selector: selects versions (evidence: `src/compliance_review/harness/orchestrator.py`)
- Review Orchestrator → Skill Loader: loads skill (evidence: `src/compliance_review/harness/orchestrator.py`)
- Review Orchestrator → K-Run Checks: runs checks (evidence: `src/compliance_review/harness/orchestrator.py`)
- Review Orchestrator → Evidence Verifier: verifies flags (evidence: `src/compliance_review/harness/orchestrator.py`)
- Review Orchestrator → Review Repository: persists results (evidence: `src/compliance_review/harness/orchestrator.py`)
- Skill Selector → Vector Index: retrieves versions
- K-Run Checks → Code Checks: runs code checks (evidence: `src/compliance_review/harness/k_run.py`)
- K-Run Checks → Disclosure Checks: runs disclosure checks (evidence: `src/compliance_review/harness/k_run.py`)
- K-Run Checks → Other Checks: runs other checks (evidence: `src/compliance_review/harness/k_run.py`)
- K-Run Checks → Evidence Verifier: normalizes evidence (evidence: `src/compliance_review/harness/k_run.py`)
- K-Run Checks → Model Client: requests inference
- Dashboard Queries → Review Repository: queries records (evidence: `src/compliance_review/dashboard/queries.py`)
- Review Repository → Database Engine: opens connections (evidence: `src/compliance_review/db/repository.py`)
- Review Repository → Database Tables: queries and writes (evidence: `src/compliance_review/db/repository.py`)
- Metrics → Database Engine: reads database (evidence: `src/compliance_review/metrics/compute.py`)
- Metrics → Database Tables: reads review data (evidence: `src/compliance_review/metrics/compute.py`)
- Metrics → Evidence Verifier: uses verification (evidence: `src/compliance_review/metrics/compute.py`)