# mrinnnmoy/kosmos architecture

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

- Interactive diagram: https://gitdiagram.com/mrinnnmoy/kosmos
- Repository: https://github.com/mrinnnmoy/kosmos

## Overview

Kosmos is a web-based event management and ticketing product: hosts create and manage events, while attendees discover events, pass a human-verification gate, join (including escrowed payment for paid events), receive tickets, check in, and earn attendance proof when events are settled. The README documents World, Uniswap, ENS, and Privy capabilities; sampled routes show join verification, persistence, and email delivery. Contract implementations are not present in the supplied tree, so on-chain behavior is represented as an external Sepolia service. Some UI-to-route wiring is not evidenced by the excerpts.

Main entry points: [`app/web/lib/db/schema.ts`](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/lib/db/schema.ts) (Application database), [`app/web/app/api/join/route.ts`](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/join/route.ts) (Join processing), [`app/web/app/api/events/[id]/route.ts`](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/events/%5Bid%5D/route.ts) (Event lifecycle API), [`app/web/app/api/join/[id]/approve/route.ts`](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/join/%5Bid%5D/approve/route.ts) (Request decisions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["Event experience"]
  node_discover["Event discovery<br/>[page.tsx]"]
  node_event_detail["Event details<br/>[page.tsx]"]
  node_event_create["Event creation<br/>[page.tsx]"]
  node_event_manage["Event management<br/>[page.tsx]"]
  node_checkin_ui["Check-in scanner<br/>[QrScanner.tsx]"]
  node_ticket_ui["Ticket QR<br/>[TicketQrButton.tsx]"]
end

subgraph group_join["Joining and payments"]
  node_world_ui["Selfie Check"]
  node_event_join_ui["Join flow<br/>[EventJoin.tsx]"]
  node_join_api["Join processing<br/>[route.ts]"]
  node_join_requests["Request decisions<br/>[route.ts]"]
  node_cancel_request["Join cancellation<br/>[route.ts]"]
  node_uniswap_ui["Swap payment UI"]
  node_swap_quote["Swap quote API<br/>[route.ts]"]
  node_swap_build["Swap build API<br/>[route.ts]"]
  node_uniswap_client["Uniswap client<br/>[client.ts]"]
end

subgraph group_identity["Identity and profiles"]
  node_auth["Privy authentication<br/>[page.tsx]"]
  node_auth_verify["Token verification"]
  node_ens_check["Subname availability<br/>[route.ts]"]
  node_ens_register["Subname registration"]
  node_ens_api["ENS registration API<br/>[route.ts]"]
end

subgraph group_runtime["Application services"]
  node_db[("Application database<br/>[schema.ts]")]
  node_world_verify["World proof verifier<br/>[verify.ts]"]
  node_email_notifications["Email notifications<br/>[notifications.tsx]"]
  node_checkin_api["Check-in API<br/>[route.ts]"]
  node_event_api["Event lifecycle API<br/>[route.ts]"]
  node_shared_abi["Shared contract ABIs<br/>[EventEscrow.ts]"]
end

node_attendee(("Attendee"))
node_host(("Event host"))
node_sep_contracts{{"Sepolia contracts"}}
node_world_service{{"World verification service"}}
node_uniswap_service{{"Uniswap Trading API"}}
node_ens_service{{"ENSv2 contracts"}}
node_privy_service{{"Privy identity service"}}

node_attendee -->|"browses"| node_discover
node_attendee -->|"views"| node_event_detail
node_host -->|"creates"| node_event_create
node_host -->|"manages"| node_event_manage
node_attendee -->|"signs in"| node_auth
node_auth -->|"authenticates"| node_privy_service
node_event_join_ui -->|"requests verification"| node_world_ui
node_world_ui -->|"obtains proof"| node_world_service
node_join_api -->|"verifies token"| node_auth_verify
node_join_api -->|"verifies proof"| node_world_verify
node_join_api -->|"reads and writes"| node_db
node_join_api -->|"sends ticket email"| node_email_notifications
node_event_join_ui -.->|"submits request"| node_join_api
node_uniswap_ui -->|"requests quote"| node_swap_quote
node_uniswap_ui -->|"requests swap"| node_swap_build
node_swap_quote -->|"uses"| node_uniswap_client
node_swap_build -->|"uses"| node_uniswap_client
node_uniswap_client -->|"quotes and builds"| node_uniswap_service
node_uniswap_ui -->|"deposits ETH"| node_sep_contracts
node_join_requests -->|"updates request"| node_db
node_join_requests -->|"sends ticket email"| node_email_notifications
node_join_requests -->|"checks escrow state"| node_sep_contracts
node_cancel_request -->|"updates request"| node_db
node_cancel_request -->|"checks refund"| node_sep_contracts
node_host -->|"checks in attendees"| node_checkin_ui
node_checkin_ui -.->|"submits ticket"| node_checkin_api
node_checkin_api -.->|"updates attendance"| node_db
node_host -->|"ends event"| node_event_api
node_event_api -->|"updates lifecycle"| node_db
node_event_api -->|"checks settlement"| node_sep_contracts
node_event_api -->|"decodes escrow"| node_shared_abi
node_attendee -->|"presents ticket"| node_ticket_ui
node_ens_check -->|"checks name"| node_db
node_ens_check -->|"checks availability"| node_ens_service
node_ens_api -->|"registers subname"| node_ens_register
node_ens_register -->|"registers identity"| node_ens_service
node_ens_api -.->|"stores profile"| node_db

click node_discover "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/discover/page.tsx"
click node_event_detail "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/discover/%5Bevent-slug%5D/page.tsx"
click node_event_create "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/create/page.tsx"
click node_event_manage "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/events/%5Bid%5D/manage/page.tsx"
click node_checkin_ui "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/components/checkin/QrScanner.tsx"
click node_ticket_ui "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/components/tickets/TicketQrButton.tsx"
click node_world_ui "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/components/worldid/SelfieCheckButton.tsx"
click node_event_join_ui "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/components/worldid/EventJoin.tsx"
click node_join_api "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/join/route.ts"
click node_join_requests "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/join/%5Bid%5D/approve/route.ts"
click node_cancel_request "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/join/%5Bid%5D/cancel/route.ts"
click node_uniswap_ui "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/components/join/UniswapPayButton.tsx"
click node_swap_quote "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/swap-quote/route.ts"
click node_swap_build "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/swap-build/route.ts"
click node_uniswap_client "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/lib/uniswap/client.ts"
click node_auth "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/signin/page.tsx"
click node_auth_verify "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/lib/auth/verify-privy-token.ts"
click node_ens_check "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/ens/check-availability/route.ts"
click node_ens_register "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/lib/ens/register-subname.ts"
click node_ens_api "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/ens/register/route.ts"
click node_db "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/lib/db/schema.ts"
click node_world_verify "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/lib/worldid/verify.ts"
click node_email_notifications "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/lib/email/notifications.tsx"
click node_checkin_api "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/checkin/%5BticketId%5D/route.ts"
click node_event_api "https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/events/%5Bid%5D/route.ts"
click node_shared_abi "https://github.com/mrinnnmoy/kosmos/blob/main/packages/shared/src/abi/EventEscrow.ts"

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_discover,node_event_detail,node_event_create,node_event_manage,node_checkin_ui,node_ticket_ui toneBlue
class node_world_ui,node_event_join_ui,node_join_api,node_join_requests,node_cancel_request,node_uniswap_ui,node_swap_quote,node_swap_build,node_uniswap_client toneAmber
class node_auth,node_auth_verify,node_ens_check,node_ens_register,node_ens_api,node_uniswap_service toneMint
class node_db,node_world_verify,node_email_notifications,node_checkin_api,node_event_api,node_shared_abi toneRose
class node_attendee,node_host,node_sep_contracts,node_world_service,node_ens_service,node_privy_service toneIndigo
```

## Components

### Event experience

- [Event discovery](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/discover/page.tsx): `app/web/app/discover/page.tsx`
- [Event details](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/discover/%5Bevent-slug%5D/page.tsx): `app/web/app/discover/[event-slug]/page.tsx`
- [Event creation](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/create/page.tsx): `app/web/app/create/page.tsx`
- [Event management](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/events/%5Bid%5D/manage/page.tsx): `app/web/app/events/[id]/manage/page.tsx`
- [Check-in scanner](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/components/checkin/QrScanner.tsx): `app/web/components/checkin/QrScanner.tsx`
- [Ticket QR](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/components/tickets/TicketQrButton.tsx): `app/web/components/tickets/TicketQrButton.tsx`

### Joining and payments

- [Selfie Check](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/components/worldid/SelfieCheckButton.tsx): `app/web/components/worldid/SelfieCheckButton.tsx`
- [Join flow](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/components/worldid/EventJoin.tsx): `app/web/components/worldid/EventJoin.tsx`
- [Join processing](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/join/route.ts): `app/web/app/api/join/route.ts`
- [Request decisions](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/join/%5Bid%5D/approve/route.ts): `app/web/app/api/join/[id]/approve/route.ts`
- [Join cancellation](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/join/%5Bid%5D/cancel/route.ts): `app/web/app/api/join/[id]/cancel/route.ts`
- [Swap payment UI](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/components/join/UniswapPayButton.tsx): `app/web/components/join/UniswapPayButton.tsx`
- [Swap quote API](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/swap-quote/route.ts): `app/web/app/api/swap-quote/route.ts`
- [Swap build API](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/swap-build/route.ts): `app/web/app/api/swap-build/route.ts`
- [Uniswap client](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/lib/uniswap/client.ts): `app/web/lib/uniswap/client.ts`

### Identity and profiles

- [Privy authentication](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/signin/page.tsx): `app/web/app/signin/page.tsx`
- [Token verification](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/lib/auth/verify-privy-token.ts): `app/web/lib/auth/verify-privy-token.ts`
- [Subname availability](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/ens/check-availability/route.ts): `app/web/app/api/ens/check-availability/route.ts`
- [Subname registration](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/lib/ens/register-subname.ts): `app/web/lib/ens/register-subname.ts`
- [ENS registration API](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/ens/register/route.ts): `app/web/app/api/ens/register/route.ts`

### Application services

- [Application database](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/lib/db/schema.ts): `app/web/lib/db/schema.ts`
- [World proof verifier](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/lib/worldid/verify.ts): `app/web/lib/worldid/verify.ts`
- [Email notifications](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/lib/email/notifications.tsx): `app/web/lib/email/notifications.tsx`
- [Check-in API](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/checkin/%5BticketId%5D/route.ts): `app/web/app/api/checkin/[ticketId]/route.ts`
- [Event lifecycle API](https://github.com/mrinnnmoy/kosmos/blob/main/app/web/app/api/events/%5Bid%5D/route.ts): `app/web/app/api/events/[id]/route.ts`
- [Shared contract ABIs](https://github.com/mrinnnmoy/kosmos/blob/main/packages/shared/src/abi/EventEscrow.ts): `packages/shared/src/abi/EventEscrow.ts`

### Other components

- **Attendee**
- **Event host**
- **Sepolia contracts**
- **World verification service**
- **Uniswap Trading API**
- **ENSv2 contracts**
- **Privy identity service**

## Connections

- Attendee → Event discovery: browses (evidence: `README.md`)
- Attendee → Event details: views (evidence: `README.md`)
- Event host → Event creation: creates (evidence: `README.md`)
- Event host → Event management: manages (evidence: `README.md`)
- Attendee → Privy authentication: signs in (evidence: `README.md`)
- Privy authentication → Privy identity service: authenticates (evidence: `README.md`)
- Join flow → Selfie Check: requests verification (evidence: `README.md`)
- Selfie Check → World verification service: obtains proof (evidence: `README.md`)
- Join processing → Token verification: verifies token (evidence: `app/web/app/api/join/route.ts`)
- Join processing → World proof verifier: verifies proof (evidence: `app/web/app/api/join/route.ts`)
- Join processing → Application database: reads and writes (evidence: `app/web/app/api/join/route.ts`)
- Join processing → Email notifications: sends ticket email (evidence: `app/web/app/api/join/route.ts`)
- Join flow → Join processing: submits request
- Swap payment UI → Swap quote API: requests quote (evidence: `README.md`)
- Swap payment UI → Swap build API: requests swap (evidence: `README.md`)
- Swap quote API → Uniswap client: uses (evidence: `README.md`)
- Swap build API → Uniswap client: uses (evidence: `README.md`)
- Uniswap client → Uniswap Trading API: quotes and builds (evidence: `README.md`)
- Swap payment UI → Sepolia contracts: deposits ETH (evidence: `README.md`)
- Request decisions → Application database: updates request (evidence: `app/web/app/api/join/[id]/approve/route.ts`)
- Request decisions → Email notifications: sends ticket email (evidence: `app/web/app/api/join/[id]/approve/route.ts`)
- Request decisions → Sepolia contracts: checks escrow state (evidence: `app/web/app/api/join/[id]/approve/route.ts`)
- Join cancellation → Application database: updates request (evidence: `app/web/app/api/join/[id]/cancel/route.ts`)
- Join cancellation → Sepolia contracts: checks refund (evidence: `app/web/app/api/join/[id]/cancel/route.ts`)
- Event host → Check-in scanner: checks in attendees (evidence: `README.md`)
- Check-in scanner → Check-in API: submits ticket
- Check-in API → Application database: updates attendance
- Event host → Event lifecycle API: ends event (evidence: `README.md`)
- Event lifecycle API → Application database: updates lifecycle (evidence: `app/web/app/api/events/[id]/route.ts`)
- Event lifecycle API → Sepolia contracts: checks settlement (evidence: `app/web/app/api/events/[id]/route.ts`)
- Event lifecycle API → Shared contract ABIs: decodes escrow (evidence: `app/web/app/api/events/[id]/route.ts`)
- Attendee → Ticket QR: presents ticket (evidence: `README.md`)
- Subname availability → Application database: checks name (evidence: `app/web/app/api/ens/check-availability/route.ts`)
- Subname availability → ENSv2 contracts: checks availability (evidence: `app/web/app/api/ens/check-availability/route.ts`)
- ENS registration API → Subname registration: registers subname (evidence: `README.md`)
- Subname registration → ENSv2 contracts: registers identity (evidence: `README.md`)
- ENS registration API → Application database: stores profile
