# oggy-and-the-cockroaches/hackwithhyderabad architecture

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

- Interactive diagram: https://gitdiagram.com/oggy-and-the-cockroaches/hackwithhyderabad
- Repository: https://github.com/oggy-and-the-cockroaches/hackwithhyderabad

## Overview

Shipcheck is a web-based pre-shipment code auditor. A developer creates or uploads a project through the dashboard, starts a scan, and views findings and historical comparisons; the backend detects project context, runs category-specific checks, and persists results. The README documents AI remediation, report export, and dashboard progress, though the sampled excerpts do not establish every implementation link. The graph uses documented architecture and sampled code; uncertain wiring is omitted.

Main entry points: [`backend/services/scanner.py`](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/services/scanner.py) (Scan Orchestrator), [`backend/main.py`](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/main.py) (FastAPI App), [`backend/api/scans.py`](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/api/scans.py) (Scan API), [`backend/services/hindsight.py`](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/services/hindsight.py) (Hindsight Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_dashboard["Dashboard SPA<br/>[app.js]"]
end

subgraph group_api["Application API"]
  node_app["FastAPI App<br/>[main.py]"]
  node_projects_api["Project API<br/>[projects.py]"]
  node_scans_api["Scan API<br/>[scans.py]"]
  node_reports_api["Reports API<br/>[reports.py]"]
  node_hindsight_api["Hindsight API<br/>[hindsight.py]"]
end

subgraph group_audit["Audit Pipeline"]
  node_project_files[("Uploaded Projects<br/>[schema.py]")]
  node_detector["Project Detector"]
  node_scanner["Scan Orchestrator<br/>[scanner.py]"]
  node_security["Security Checks<br/>[security.py]"]
  node_privacy["Privacy Checks<br/>[privacy.py]"]
  node_production["Production Checks<br/>[production.py]"]
  node_reliability["Reliability Checks<br/>[reliability.py]"]
  node_finding_model["Finding Model<br/>[base.py]"]
  node_llm["AI Remediation<br/>[llm.py]"]
end

subgraph group_memory["Reports And Memory"]
  node_sqlite[("SQLite Store<br/>[schema.py]")]
  node_hindsight["Hindsight Service<br/>[hindsight.py]"]
end

node_developer(("Developer"))
node_gemini["Gemini API"]
node_grok["Grok API"]

node_developer -->|"uses"| node_dashboard
node_dashboard -->|"HTTP requests"| node_app
node_app -->|"mounts router"| node_projects_api
node_app -->|"mounts router"| node_scans_api
node_app -->|"mounts router"| node_reports_api
node_app -->|"mounts router"| node_hindsight_api
node_projects_api -->|"reads and writes"| node_sqlite
node_projects_api -->|"stores uploads"| node_project_files
node_scans_api -->|"records scan"| node_sqlite
node_scans_api -->|"detects context"| node_detector
node_scans_api -->|"runs scan"| node_scanner
node_detector -->|"inspects project"| node_project_files
node_scanner -->|"scans files"| node_project_files
node_scanner -->|"dispatches"| node_security
node_scanner -->|"dispatches"| node_privacy
node_scanner -->|"dispatches"| node_production
node_scanner -->|"dispatches"| node_reliability
node_security -->|"creates findings"| node_finding_model
node_privacy -->|"creates findings"| node_finding_model
node_production -->|"creates findings"| node_finding_model
node_reliability -->|"creates findings"| node_finding_model
node_scanner -->|"requests remediation"| node_llm
node_llm -.->|"generates analysis"| node_gemini
node_llm -.->|"generates analysis"| node_grok
node_scans_api -->|"persists and compares"| node_hindsight
node_hindsight -->|"stores history"| node_sqlite
node_reports_api -->|"reads and updates"| node_sqlite
node_reports_api -->|"compares scans and notes"| node_hindsight
node_hindsight_api -->|"records memory"| node_hindsight
node_dashboard -->|"retrieves reports"| node_reports_api
node_hindsight -.->|"retains scan context"| node_gemini

click node_dashboard "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/frontend/app.js"
click node_app "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/main.py"
click node_projects_api "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/api/projects.py"
click node_scans_api "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/api/scans.py"
click node_reports_api "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/api/reports.py"
click node_hindsight_api "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/api/hindsight.py"
click node_project_files "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/database/schema.py"
click node_detector "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/services/project_detector.py"
click node_scanner "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/services/scanner.py"
click node_security "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/scanners/security.py"
click node_privacy "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/scanners/privacy.py"
click node_production "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/scanners/production.py"
click node_reliability "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/scanners/reliability.py"
click node_finding_model "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/scanners/base.py"
click node_llm "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/services/llm.py"
click node_sqlite "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/database/schema.py"
click node_hindsight "https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/services/hindsight.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 toneBlue
class node_app,node_projects_api,node_scans_api,node_reports_api,node_hindsight_api toneAmber
class node_project_files,node_detector,node_scanner,node_security,node_privacy,node_production,node_reliability,node_finding_model,node_llm,node_gemini,node_grok toneMint
class node_sqlite,node_hindsight toneRose
class node_developer toneIndigo
```

## Components

### Dashboard

- [Dashboard SPA](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/frontend/app.js): `frontend/app.js`

### Application API

- [FastAPI App](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/main.py): `backend/main.py`
- [Project API](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/api/projects.py): `backend/api/projects.py`
- [Scan API](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/api/scans.py): `backend/api/scans.py`
- [Reports API](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/api/reports.py): `backend/api/reports.py`
- [Hindsight API](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/api/hindsight.py): `backend/api/hindsight.py`

### Audit Pipeline

- [Uploaded Projects](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/database/schema.py): `backend/database/schema.py`
- [Project Detector](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/services/project_detector.py): `backend/services/project_detector.py`
- [Scan Orchestrator](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/services/scanner.py): `backend/services/scanner.py`
- [Security Checks](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/scanners/security.py): `backend/scanners/security.py`
- [Privacy Checks](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/scanners/privacy.py): `backend/scanners/privacy.py`
- [Production Checks](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/scanners/production.py): `backend/scanners/production.py`
- [Reliability Checks](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/scanners/reliability.py): `backend/scanners/reliability.py`
- [Finding Model](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/scanners/base.py): `backend/scanners/base.py`
- [AI Remediation](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/services/llm.py): `backend/services/llm.py`

### Reports And Memory

- [SQLite Store](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/database/schema.py): `backend/database/schema.py`
- [Hindsight Service](https://github.com/oggy-and-the-cockroaches/hackwithhyderabad/blob/main/backend/services/hindsight.py): `backend/services/hindsight.py`

### Other components

- **Developer**
- **Gemini API**
- **Grok API**

## Connections

- Developer → Dashboard SPA: uses
- Dashboard SPA → FastAPI App: HTTP requests
- FastAPI App → Project API: mounts router
- FastAPI App → Scan API: mounts router
- FastAPI App → Reports API: mounts router
- FastAPI App → Hindsight API: mounts router
- Project API → SQLite Store: reads and writes
- Project API → Uploaded Projects: stores uploads
- Scan API → SQLite Store: records scan
- Scan API → Project Detector: detects context
- Scan API → Scan Orchestrator: runs scan
- Project Detector → Uploaded Projects: inspects project
- Scan Orchestrator → Uploaded Projects: scans files
- Scan Orchestrator → Security Checks: dispatches
- Scan Orchestrator → Privacy Checks: dispatches
- Scan Orchestrator → Production Checks: dispatches
- Scan Orchestrator → Reliability Checks: dispatches
- Security Checks → Finding Model: creates findings
- Privacy Checks → Finding Model: creates findings
- Production Checks → Finding Model: creates findings
- Reliability Checks → Finding Model: creates findings
- Scan Orchestrator → AI Remediation: requests remediation
- AI Remediation → Gemini API: generates analysis
- AI Remediation → Grok API: generates analysis
- Scan API → Hindsight Service: persists and compares
- Hindsight Service → SQLite Store: stores history
- Reports API → SQLite Store: reads and updates
- Reports API → Hindsight Service: compares scans and notes
- Hindsight API → Hindsight Service: records memory
- Dashboard SPA → Reports API: retrieves reports
- Hindsight Service → Gemini API: retains scan context