# aballal-source/bughunt architecture

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

- Interactive diagram: https://gitdiagram.com/aballal-source/bughunt
- Repository: https://github.com/aballal-source/bughunt

## Overview

BugHunt is a crowdsourced game-bug reporting platform. Players browse reports, submit bugs, and upvote; an admin can triage report status, while users can inspect SQL-backed analytics. The React app calls a FastAPI REST API, whose feature routers use a shared PostgreSQL connection helper. The README documents game management and analytics capabilities beyond the sampled source; their router paths are present in the tree, but their internal query behavior was not inspected.

Main entry points: [`frontend/src/services/api.js`](https://github.com/aballal-source/bughunt/blob/main/frontend/src/services/api.js) (API client), [`frontend/src/App.jsx`](https://github.com/aballal-source/bughunt/blob/main/frontend/src/App.jsx) (App shell), [`frontend/src/components/BugForm.jsx`](https://github.com/aballal-source/bughunt/blob/main/frontend/src/components/BugForm.jsx) (Bug submission), [`backend/database.py`](https://github.com/aballal-source/bughunt/blob/main/backend/database.py) (DB connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["React web app"]
  node_app["App shell<br/>[App.jsx]"]
  node_bugform["Bug submission<br/>[BugForm.jsx]"]
  node_buglist["Bug list<br/>[BugList.jsx]"]
  node_bugcard["Bug card<br/>[BugCard.jsx]"]
  node_adminpanel["Admin triage<br/>[AdminPanel.jsx]"]
  node_analyticsui["Analytics dashboard"]
  node_apiservice["API client<br/>[api.js]"]
end

subgraph group_api["REST API"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_bugroutes["Bug reports<br/>[bugs.py]"]
  node_gameroutes["Game catalog<br/>[games.py]"]
  node_analyticsroutes["Analytics queries<br/>[analytics.py]"]
  node_connection["DB connection<br/>[database.py]"]
end

subgraph group_data["PostgreSQL data"]
  node_postgres[("PostgreSQL")]
end

node_player(("Player"))
node_administrator(("Administrator"))

node_player -->|"submits report"| node_bugform
node_player -->|"browses reports"| node_buglist
node_player -->|"upvotes report"| node_bugcard
node_administrator -->|"triages reports"| node_adminpanel
node_app -->|"renders"| node_bugform
node_app -->|"renders"| node_buglist
node_app -->|"renders"| node_adminpanel
node_app -->|"renders"| node_analyticsui
node_app -->|"loads reports"| node_apiservice
node_bugform -->|"loads games"| node_apiservice
node_bugform -->|"submits bug"| node_apiservice
node_buglist -->|"renders"| node_bugcard
node_bugcard -->|"upvotes bug"| node_apiservice
node_adminpanel -->|"updates status"| node_apiservice
node_analyticsui -->|"loads analytics"| node_apiservice
node_apiservice -->|"HTTP requests"| node_bugroutes
node_apiservice -->|"HTTP requests"| node_gameroutes
node_apiservice -->|"HTTP requests"| node_analyticsroutes
node_fastapi -->|"mounts routes"| node_bugroutes
node_fastapi -->|"mounts routes"| node_gameroutes
node_fastapi -->|"mounts routes"| node_analyticsroutes
node_bugroutes -->|"opens connection"| node_connection
node_gameroutes -->|"opens connection"| node_connection
node_analyticsroutes -->|"opens connection"| node_connection
node_connection -->|"connects"| node_postgres

click node_app "https://github.com/aballal-source/bughunt/blob/main/frontend/src/App.jsx"
click node_bugform "https://github.com/aballal-source/bughunt/blob/main/frontend/src/components/BugForm.jsx"
click node_buglist "https://github.com/aballal-source/bughunt/blob/main/frontend/src/components/BugList.jsx"
click node_bugcard "https://github.com/aballal-source/bughunt/blob/main/frontend/src/components/BugCard.jsx"
click node_adminpanel "https://github.com/aballal-source/bughunt/blob/main/frontend/src/components/AdminPanel.jsx"
click node_analyticsui "https://github.com/aballal-source/bughunt/blob/main/frontend/src/components/AnalyticsDashboard.jsx"
click node_apiservice "https://github.com/aballal-source/bughunt/blob/main/frontend/src/services/api.js"
click node_fastapi "https://github.com/aballal-source/bughunt/blob/main/backend/main.py"
click node_bugroutes "https://github.com/aballal-source/bughunt/blob/main/backend/routers/bugs.py"
click node_gameroutes "https://github.com/aballal-source/bughunt/blob/main/backend/routers/games.py"
click node_analyticsroutes "https://github.com/aballal-source/bughunt/blob/main/backend/routers/analytics.py"
click node_connection "https://github.com/aballal-source/bughunt/blob/main/backend/database.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_app,node_bugform,node_buglist,node_bugcard,node_adminpanel,node_analyticsui,node_apiservice toneBlue
class node_fastapi,node_bugroutes,node_gameroutes,node_analyticsroutes,node_connection toneAmber
class node_postgres toneMint
class node_player,node_administrator toneIndigo
```

## Components

### React web app

- [App shell](https://github.com/aballal-source/bughunt/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Bug submission](https://github.com/aballal-source/bughunt/blob/main/frontend/src/components/BugForm.jsx): `frontend/src/components/BugForm.jsx`
- [Bug list](https://github.com/aballal-source/bughunt/blob/main/frontend/src/components/BugList.jsx): `frontend/src/components/BugList.jsx`
- [Bug card](https://github.com/aballal-source/bughunt/blob/main/frontend/src/components/BugCard.jsx): `frontend/src/components/BugCard.jsx`
- [Admin triage](https://github.com/aballal-source/bughunt/blob/main/frontend/src/components/AdminPanel.jsx): `frontend/src/components/AdminPanel.jsx`
- [Analytics dashboard](https://github.com/aballal-source/bughunt/blob/main/frontend/src/components/AnalyticsDashboard.jsx): `frontend/src/components/AnalyticsDashboard.jsx`
- [API client](https://github.com/aballal-source/bughunt/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### REST API

- [FastAPI app](https://github.com/aballal-source/bughunt/blob/main/backend/main.py): `backend/main.py`
- [Bug reports](https://github.com/aballal-source/bughunt/blob/main/backend/routers/bugs.py): `backend/routers/bugs.py`
- [Game catalog](https://github.com/aballal-source/bughunt/blob/main/backend/routers/games.py): `backend/routers/games.py`
- [Analytics queries](https://github.com/aballal-source/bughunt/blob/main/backend/routers/analytics.py): `backend/routers/analytics.py`
- [DB connection](https://github.com/aballal-source/bughunt/blob/main/backend/database.py): `backend/database.py`

### PostgreSQL data

- **PostgreSQL**

### Other components

- **Player**
- **Administrator**

## Connections

- Player → Bug submission: submits report
- Player → Bug list: browses reports
- Player → Bug card: upvotes report
- Administrator → Admin triage: triages reports
- App shell → Bug submission: renders
- App shell → Bug list: renders
- App shell → Admin triage: renders
- App shell → Analytics dashboard: renders
- App shell → API client: loads reports
- Bug submission → API client: loads games
- Bug submission → API client: submits bug
- Bug list → Bug card: renders
- Bug card → API client: upvotes bug
- Admin triage → API client: updates status
- Analytics dashboard → API client: loads analytics
- API client → Bug reports: HTTP requests
- API client → Game catalog: HTTP requests
- API client → Analytics queries: HTTP requests
- FastAPI app → Bug reports: mounts routes
- FastAPI app → Game catalog: mounts routes
- FastAPI app → Analytics queries: mounts routes
- Bug reports → DB connection: opens connection
- Game catalog → DB connection: opens connection
- Analytics queries → DB connection: opens connection
- DB connection → PostgreSQL: connects