# tejaswee-06/bnb26_twopointers_internal_round architecture

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

- Interactive diagram: https://gitdiagram.com/tejaswee-06/bnb26_twopointers_internal_round
- Repository: https://github.com/tejaswee-06/bnb26_twopointers_internal_round

## Overview

FairDrop is a ticket-drop platform: customers join a fair pre-queue, receive a randomized rank, pass controlled admission, reserve and confirm inventory, then verify the result. The authoritative FastAPI backend owns this flow; the Next.js site proxies live requests, while its separate browser simulator supports an attack lab. An advisory ML service supplies RiskEvents to deterministic policy enforcement, and organizers operate the drop through an admin console. The graph follows documented flows and indexed source references; several frontend and API subsystem internals were not sampled, so their detailed links are omitted.

Main entry points: [`backend/app/api`](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/tree/main/backend/app/api) (FastAPI routes), [`backend/app/policy/service.py`](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/policy/service.py) (Policy ingestion), [`backend/app/services/session_service.py`](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/services/session_service.py) (Session lifecycle), [`backend/app/repositories/inventory_repository.py`](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/repositories/inventory_repository.py) (Inventory repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_customer["Customer experience"]
  node_customer_site["Customer site"]
  node_live_proxy["Live API proxy<br/>[route.ts]"]
end

subgraph group_backend["Authoritative backend"]
  node_backend_api["FastAPI routes"]
  node_session_service["Session lifecycle<br/>[session_service.py]"]
  node_drop_service["Fair drop lifecycle<br/>[drop_service.py]"]
  node_queue_store["Queue store<br/>[store.py]"]
  node_allocation_service["Allocation service"]
  node_inventory_repo["Inventory repository"]
  node_database[("Authoritative database<br/>[database.py]")]
  node_session_records["Session records<br/>[session.py]"]
  node_inventory_records["Inventory records<br/>[inventory.py]"]
end

subgraph group_policy["Risk and policy"]
  node_policy_service["Policy ingestion<br/>[service.py]"]
  node_policy_engine["Deterministic policy<br/>[engine.py]"]
  node_ml_service["ML evidence API<br/>[main.py]"]
  node_telemetry["Audit telemetry<br/>[service.py]"]
end

subgraph group_operations["Operations and simulation"]
  node_admin_console["Organizer console"]
  node_browser_sim["Attack simulator<br/>[drop.ts]"]
  node_resilience["Resilience controller<br/>[controller.py]"]
  node_expiry_worker["Expiry worker<br/>[expiry.py]"]
end

node_customer_actor(("Customer"))
node_organizer_actor(("Organizer"))

node_customer_actor -->|"uses"| node_customer_site
node_customer_site -->|"requests live API"| node_live_proxy
node_live_proxy -->|"proxies requests"| node_backend_api
node_organizer_actor -->|"operates"| node_admin_console
node_admin_console -->|"uses proxy"| node_live_proxy
node_customer_actor -->|"runs attack lab"| node_browser_sim
node_backend_api -->|"handles sessions"| node_session_service
node_backend_api -->|"controls drops"| node_drop_service
node_backend_api -->|"requests allocation"| node_allocation_service
node_session_service -->|"advances phase"| node_drop_service
node_session_service -->|"reads queue"| node_queue_store
node_drop_service -->|"writes ranks"| node_queue_store
node_allocation_service -->|"claims inventory"| node_inventory_repo
node_inventory_repo -->|"updates inventory"| node_inventory_records
node_inventory_repo -->|"queries records"| node_database
node_session_service -->|"reads and writes"| node_session_records
node_session_records -->|"persists in"| node_database
node_allocation_service -->|"checks policy"| node_policy_service
node_policy_service -->|"evaluates event"| node_policy_engine
node_ml_service -->|"supplies RiskEvents"| node_policy_service
node_policy_service -->|"stores decisions"| node_database
node_policy_service -->|"enforces policy"| node_queue_store
node_policy_service -.->|"records activity"| node_telemetry
node_backend_api -->|"exposes controls"| node_resilience
node_backend_api -->|"starts worker"| node_expiry_worker
node_expiry_worker -.->|"expires holds"| node_inventory_repo

click node_customer_site "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/tree/main/frontend/app/(site)"
click node_live_proxy "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/frontend/app/api/fd/%5B...path%5D/route.ts"
click node_admin_console "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/tree/main/frontend/app/admin/(console)"
click node_browser_sim "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/frontend/lib/engine/drop.ts"
click node_backend_api "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/tree/main/backend/app/api"
click node_session_service "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/services/session_service.py"
click node_drop_service "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/services/drop_service.py"
click node_queue_store "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/queue/store.py"
click node_allocation_service "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/services/allocation_service.py"
click node_inventory_repo "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/repositories/inventory_repository.py"
click node_database "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/db/database.py"
click node_session_records "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/models/session.py"
click node_inventory_records "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/models/inventory.py"
click node_policy_service "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/policy/service.py"
click node_policy_engine "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/policy/engine.py"
click node_ml_service "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/ml_api/main.py"
click node_telemetry "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/telemetry/service.py"
click node_resilience "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/resilience/controller.py"
click node_expiry_worker "https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/workers/expiry.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_customer_site,node_live_proxy toneBlue
class node_backend_api,node_session_service,node_drop_service,node_queue_store,node_allocation_service,node_inventory_repo,node_database,node_session_records,node_inventory_records toneAmber
class node_policy_service,node_policy_engine,node_ml_service,node_telemetry toneMint
class node_admin_console,node_browser_sim,node_resilience,node_expiry_worker toneRose
class node_customer_actor,node_organizer_actor toneIndigo
```

## Components

### Customer experience

- [Customer site](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/tree/main/frontend/app/(site)): `frontend/app/(site)`
- [Live API proxy](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/frontend/app/api/fd/%5B...path%5D/route.ts): `frontend/app/api/fd/[...path]/route.ts`

### Authoritative backend

- [FastAPI routes](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/tree/main/backend/app/api): `backend/app/api`
- [Session lifecycle](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/services/session_service.py): `backend/app/services/session_service.py`
- [Fair drop lifecycle](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/services/drop_service.py): `backend/app/services/drop_service.py`
- [Queue store](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/queue/store.py): `backend/app/queue/store.py`
- [Allocation service](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/services/allocation_service.py): `backend/app/services/allocation_service.py`
- [Inventory repository](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/repositories/inventory_repository.py): `backend/app/repositories/inventory_repository.py`
- [Authoritative database](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/db/database.py): `backend/app/db/database.py`
- [Session records](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/models/session.py): `backend/app/models/session.py`
- [Inventory records](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/models/inventory.py): `backend/app/models/inventory.py`

### Risk and policy

- [Policy ingestion](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/policy/service.py): `backend/app/policy/service.py`
- [Deterministic policy](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/policy/engine.py): `backend/app/policy/engine.py`
- [ML evidence API](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/ml_api/main.py): `ml_api/main.py`
- [Audit telemetry](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/telemetry/service.py): `backend/app/telemetry/service.py`

### Operations and simulation

- [Organizer console](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/tree/main/frontend/app/admin/(console)): `frontend/app/admin/(console)`
- [Attack simulator](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/frontend/lib/engine/drop.ts): `frontend/lib/engine/drop.ts`
- [Resilience controller](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/resilience/controller.py): `backend/app/resilience/controller.py`
- [Expiry worker](https://github.com/tejaswee-06/bnb26_twopointers_internal_round/blob/main/backend/app/workers/expiry.py): `backend/app/workers/expiry.py`

### Other components

- **Customer**
- **Organizer**

## Connections

- Customer → Customer site: uses
- Customer site → Live API proxy: requests live API
- Live API proxy → FastAPI routes: proxies requests
- Organizer → Organizer console: operates
- Organizer console → Live API proxy: uses proxy
- Customer → Attack simulator: runs attack lab
- FastAPI routes → Session lifecycle: handles sessions
- FastAPI routes → Fair drop lifecycle: controls drops (evidence: `backend/app/api/admin.py`)
- FastAPI routes → Allocation service: requests allocation (evidence: `backend/app/api/allocation.py`)
- Session lifecycle → Fair drop lifecycle: advances phase (evidence: `backend/app/services/session_service.py`)
- Session lifecycle → Queue store: reads queue (evidence: `backend/app/services/session_service.py`)
- Fair drop lifecycle → Queue store: writes ranks (evidence: `backend/app/services/drop_service.py`)
- Allocation service → Inventory repository: claims inventory (evidence: `backend/app/services/allocation_service.py`)
- Inventory repository → Inventory records: updates inventory (evidence: `backend/app/repositories/inventory_repository.py`)
- Inventory repository → Authoritative database: queries records (evidence: `backend/app/repositories/inventory_repository.py`)
- Session lifecycle → Session records: reads and writes (evidence: `backend/app/services/session_service.py`)
- Session records → Authoritative database: persists in (evidence: `backend/app/models/session.py`)
- Allocation service → Policy ingestion: checks policy (evidence: `backend/app/services/allocation_service.py`)
- Policy ingestion → Deterministic policy: evaluates event (evidence: `backend/app/policy/service.py`)
- ML evidence API → Policy ingestion: supplies RiskEvents
- Policy ingestion → Authoritative database: stores decisions (evidence: `backend/app/policy/service.py`)
- Policy ingestion → Queue store: enforces policy (evidence: `backend/app/policy/service.py`)
- Policy ingestion → Audit telemetry: records activity
- FastAPI routes → Resilience controller: exposes controls
- FastAPI routes → Expiry worker: starts worker (evidence: `backend/app/main.py`)
- Expiry worker → Inventory repository: expires holds
