# niko-2182/bnb26_penguins_maharashtra_round architecture

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

- Interactive diagram: https://gitdiagram.com/niko-2182/bnb26_penguins_maharashtra_round
- Repository: https://github.com/niko-2182/bnb26_penguins_maharashtra_round

## Overview

FairDrop is a ticket-allocation API designed to resist bots with proof-of-work, trust scoring, and weighted random selection. Its visible workflow is client join and verification, followed by a claim attempt that atomically checks eligibility and seat availability. The API also exposes session, metrics, ledger, and admin endpoints. The graph reflects the sampled runtime code and README; several documented capabilities are retained, but unsampled handler and persistence behavior limits which connections can be verified.

Main entry points: [`api/internal/httpx/router.go`](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/httpx/router.go) (Route dispatch), [`api/internal/session/session.go`](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/session/session.go) (Session manager), [`api/internal/store/redis.go`](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/store/redis.go) (Redis client), [`api/internal/metrics/service.go`](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/metrics/service.go) (Metrics service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API surface"]
  node_server["HTTP server<br/>[main.go]"]
  node_router["Route dispatch<br/>[router.go]"]
  node_join["Join endpoint<br/>[join.go]"]
  node_verify["Verify endpoint<br/>[verify.go]"]
  node_session_endpoint["Session endpoint<br/>[session.go]"]
  node_claim_endpoint["Claim endpoint<br/>[claim.go]"]
end

subgraph group_eligibility["Eligibility checks"]
  node_session_manager["Session manager<br/>[session.go]"]
  node_rate_limiter["Rate limiter<br/>[ratelimit.go]"]
  node_pow["Proof of work<br/>[pow.go]"]
  node_trust["Trust scoring<br/>[trust.go]"]
end

subgraph group_allocation["Allocation and state"]
  node_allocator["Seat allocator<br/>[claim.go]"]
  node_redis_client["Redis client<br/>[redis.go]"]
  node_redis[("Redis")]
  node_session_store["Session persistence<br/>[store.go]"]
end

subgraph group_observability["Operations and reporting"]
  node_ledger_endpoint["Ledger endpoint<br/>[router.go]"]
  node_ledger_service["Ledger service<br/>[service.go]"]
  node_ledger_store["Ledger persistence<br/>[store.go]"]
  node_metrics_endpoint["Metrics endpoint<br/>[router.go]"]
  node_metrics_service["Metrics service<br/>[service.go]"]
  node_admin["Admin endpoints<br/>[router.go]"]
end

node_client(("Client"))

node_client -->|"sends requests"| node_server
node_server -->|"serves routes"| node_router
node_router -->|"routes join"| node_join
node_router -->|"routes verify"| node_verify
node_router -->|"routes session"| node_session_endpoint
node_router -->|"routes claim"| node_claim_endpoint
node_router -->|"serves ledger"| node_ledger_endpoint
node_router -->|"serves metrics"| node_metrics_endpoint
node_router -->|"serves admin"| node_admin
node_router -->|"creates manager"| node_session_manager
node_router -->|"creates service"| node_ledger_service
node_router -->|"creates service"| node_metrics_service
node_session_manager -->|"checks limits"| node_rate_limiter
node_session_manager -->|"gets trust score"| node_trust
node_session_manager -->|"verifies proof"| node_pow
node_session_manager -->|"uses client"| node_redis_client
node_claim_endpoint -->|"gets trust score"| node_trust
node_claim_endpoint -->|"attempts claim"| node_allocator
node_allocator -->|"executes script"| node_redis_client
node_redis_client -->|"accesses data"| node_redis
node_ledger_endpoint -->|"reads events"| node_ledger_service
node_ledger_service -->|"reads or records"| node_ledger_store
node_metrics_endpoint -->|"gets metrics"| node_metrics_service
node_metrics_service -->|"reads recent events"| node_ledger_service
node_metrics_service -->|"reads counters"| node_redis_client
node_admin -->|"updates state"| node_redis_client

click node_server "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/main.go"
click node_router "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/httpx/router.go"
click node_join "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/handlers/join.go"
click node_verify "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/handlers/verify.go"
click node_session_endpoint "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/handlers/session.go"
click node_claim_endpoint "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/handlers/claim.go"
click node_session_manager "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/session/session.go"
click node_rate_limiter "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/abuse/ratelimit.go"
click node_pow "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/abuse/pow.go"
click node_trust "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/abuse/trust.go"
click node_allocator "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/allocator/claim.go"
click node_redis_client "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/store/redis.go"
click node_session_store "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/session/store.go"
click node_ledger_endpoint "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/httpx/router.go"
click node_ledger_service "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/ledger/service.go"
click node_ledger_store "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/ledger/store.go"
click node_metrics_endpoint "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/httpx/router.go"
click node_metrics_service "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/metrics/service.go"
click node_admin "https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/httpx/router.go"

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_server,node_router,node_join,node_verify,node_session_endpoint,node_claim_endpoint,node_client toneBlue
class node_session_manager,node_rate_limiter,node_pow,node_trust toneAmber
class node_allocator,node_redis_client,node_redis,node_session_store toneMint
class node_ledger_endpoint,node_ledger_service,node_ledger_store,node_metrics_endpoint,node_metrics_service,node_admin toneRose
```

## Components

### API surface

- [HTTP server](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/main.go): `api/main.go`
- [Route dispatch](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/httpx/router.go): `api/internal/httpx/router.go`
- [Join endpoint](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/handlers/join.go): `api/internal/handlers/join.go`
- [Verify endpoint](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/handlers/verify.go): `api/internal/handlers/verify.go`
- [Session endpoint](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/handlers/session.go): `api/internal/handlers/session.go`
- [Claim endpoint](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/handlers/claim.go): `api/internal/handlers/claim.go`

### Eligibility checks

- [Session manager](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/session/session.go): `api/internal/session/session.go`
- [Rate limiter](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/abuse/ratelimit.go): `api/internal/abuse/ratelimit.go`
- [Proof of work](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/abuse/pow.go): `api/internal/abuse/pow.go`
- [Trust scoring](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/abuse/trust.go): `api/internal/abuse/trust.go`

### Allocation and state

- [Seat allocator](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/allocator/claim.go): `api/internal/allocator/claim.go`
- [Redis client](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/store/redis.go): `api/internal/store/redis.go`
- **Redis**
- [Session persistence](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/session/store.go): `api/internal/session/store.go`

### Operations and reporting

- [Ledger endpoint](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/httpx/router.go): `api/internal/httpx/router.go`
- [Ledger service](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/ledger/service.go): `api/internal/ledger/service.go`
- [Ledger persistence](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/ledger/store.go): `api/internal/ledger/store.go`
- [Metrics endpoint](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/httpx/router.go): `api/internal/httpx/router.go`
- [Metrics service](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/metrics/service.go): `api/internal/metrics/service.go`
- [Admin endpoints](https://github.com/niko-2182/bnb26_penguins_maharashtra_round/blob/main/api/internal/httpx/router.go): `api/internal/httpx/router.go`

### Other components

- **Client**

## Connections

- Client → HTTP server: sends requests
- HTTP server → Route dispatch: serves routes (evidence: `api/main.go`)
- Route dispatch → Join endpoint: routes join (evidence: `api/internal/httpx/router.go`)
- Route dispatch → Verify endpoint: routes verify (evidence: `api/internal/httpx/router.go`)
- Route dispatch → Session endpoint: routes session (evidence: `api/internal/httpx/router.go`)
- Route dispatch → Claim endpoint: routes claim (evidence: `api/internal/httpx/router.go`)
- Route dispatch → Ledger endpoint: serves ledger (evidence: `api/internal/httpx/router.go`)
- Route dispatch → Metrics endpoint: serves metrics (evidence: `api/internal/httpx/router.go`)
- Route dispatch → Admin endpoints: serves admin (evidence: `api/internal/httpx/router.go`)
- Route dispatch → Session manager: creates manager (evidence: `api/internal/httpx/router.go`)
- Route dispatch → Ledger service: creates service (evidence: `api/internal/httpx/router.go`)
- Route dispatch → Metrics service: creates service (evidence: `api/internal/httpx/router.go`)
- Session manager → Rate limiter: checks limits (evidence: `api/internal/session/session.go`)
- Session manager → Trust scoring: gets trust score (evidence: `api/internal/session/session.go`)
- Session manager → Proof of work: verifies proof (evidence: `api/internal/session/session.go`)
- Session manager → Redis client: uses client (evidence: `api/internal/session/session.go`)
- Claim endpoint → Trust scoring: gets trust score (evidence: `api/internal/handlers/claim.go`)
- Claim endpoint → Seat allocator: attempts claim (evidence: `api/internal/handlers/claim.go`)
- Seat allocator → Redis client: executes script (evidence: `api/internal/allocator/claim.go`)
- Redis client → Redis: accesses data (evidence: `api/internal/store/redis.go`)
- Ledger endpoint → Ledger service: reads events (evidence: `api/internal/httpx/router.go`)
- Ledger service → Ledger persistence: reads or records (evidence: `api/internal/ledger/service.go`)
- Metrics endpoint → Metrics service: gets metrics (evidence: `api/internal/httpx/router.go`)
- Metrics service → Ledger service: reads recent events (evidence: `api/internal/metrics/service.go`)
- Metrics service → Redis client: reads counters (evidence: `api/internal/metrics/service.go`)
- Admin endpoints → Redis client: updates state (evidence: `api/internal/httpx/router.go`)
