# jlassisamer/ribat-4hack architecture

> Architecture diagram of the GitHub repository jlassisamer/ribat-4hack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jlassisamer/ribat-4hack
- Repository: https://github.com/jlassisamer/ribat-4hack

## Overview

Ribat is a web application with a React client and a small tRPC server. The visible user journey enters through the client router and reaches Home or a nullifier-based verification page; the repository also includes AI chat, maps, and a demo-data module. Server capabilities shown include authentication, owner notifications, and user persistence, alongside platform storage helpers. No README was provided, and several feature implementations were not excerpted, so their internal flows and links are not asserted.

Main entry points: [`client/src/App.tsx`](https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/App.tsx) (App routes), [`server/db.ts`](https://github.com/jlassisamer/ribat-4hack/blob/main/server/db.ts) (User database), [`server/_core/oauth.ts`](https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/oauth.ts) (OAuth flow), [`client/src/main.tsx`](https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/main.tsx) (Client bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_client_entry["Client bootstrap<br/>[main.tsx]"]
  node_app_router["App routes<br/>[App.tsx]"]
  node_home["Home experience<br/>[Home.tsx]"]
  node_verify["Verification page<br/>[Verify.tsx]"]
  node_chat["AI chat<br/>[AIChatBox.tsx]"]
  node_map["Map view<br/>[Map.tsx]"]
  node_demo["Demo data<br/>[ribat-demo.ts]"]
  node_theme["Theme context<br/>[ThemeContext.tsx]"]
  node_auth_hook["Client auth hook<br/>[useAuth.ts]"]
end

subgraph group_api["API and auth"]
  node_server_router["API router<br/>[routers.ts]"]
  node_trpc["tRPC procedures<br/>[trpc.ts]"]
  node_context["Request context<br/>[context.ts]"]
  node_system["System endpoints<br/>[systemRouter.ts]"]
  node_oauth["OAuth flow<br/>[oauth.ts]"]
  node_cookies["Session cookies<br/>[cookies.ts]"]
end

subgraph group_platform["Platform services"]
  node_notify["Owner notifications<br/>[notification.ts]"]
  node_sdk["Platform SDK<br/>[sdk.ts]"]
  node_storage["Storage helpers<br/>[storage.ts]"]
  node_storage_proxy["Storage proxy<br/>[storageProxy.ts]"]
  node_env["Environment config<br/>[env.ts]"]
end

subgraph group_data["Persistence"]
  node_database[("User database<br/>[db.ts]")]
  node_schema["User schema<br/>[schema.ts]"]
end

node_user(("Visitor"))
node_forge{{"Forge storage API"}}

node_user -->|"opens app"| node_client_entry
node_client_entry -->|"renders"| node_app_router
node_app_router -->|"routes to"| node_home
node_app_router -->|"routes to"| node_verify
node_app_router -->|"provides theme"| node_theme
node_client_entry -->|"calls API"| node_server_router
node_server_router -->|"registers procedures"| node_trpc
node_server_router -->|"mounts"| node_system
node_system -->|"uses procedures"| node_trpc
node_system -->|"notifies owner"| node_notify
node_trpc -->|"builds context"| node_context
node_context -->|"uses"| node_sdk
node_context -.->|"reads user data"| node_database
node_oauth -.->|"persists users"| node_database
node_oauth -->|"manages session"| node_cookies
node_oauth -->|"uses"| node_sdk
node_database -->|"queries schema"| node_schema
node_sdk -.->|"uses"| node_database
node_notify -->|"reads config"| node_env
node_storage -->|"reads config"| node_env
node_storage -->|"requests presigned URLs"| node_forge
node_storage_proxy -->|"requests signed URLs"| node_forge
node_storage_proxy -->|"reads config"| node_env

click node_client_entry "https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/main.tsx"
click node_app_router "https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/App.tsx"
click node_home "https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/pages/Home.tsx"
click node_verify "https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/pages/Verify.tsx"
click node_chat "https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/components/AIChatBox.tsx"
click node_map "https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/components/Map.tsx"
click node_demo "https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/lib/ribat-demo.ts"
click node_theme "https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/contexts/ThemeContext.tsx"
click node_auth_hook "https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/_core/hooks/useAuth.ts"
click node_server_router "https://github.com/jlassisamer/ribat-4hack/blob/main/server/routers.ts"
click node_trpc "https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/trpc.ts"
click node_context "https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/context.ts"
click node_system "https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/systemRouter.ts"
click node_oauth "https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/oauth.ts"
click node_cookies "https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/cookies.ts"
click node_notify "https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/notification.ts"
click node_sdk "https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/sdk.ts"
click node_storage "https://github.com/jlassisamer/ribat-4hack/blob/main/server/storage.ts"
click node_storage_proxy "https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/storageProxy.ts"
click node_database "https://github.com/jlassisamer/ribat-4hack/blob/main/server/db.ts"
click node_schema "https://github.com/jlassisamer/ribat-4hack/blob/main/drizzle/schema.ts"
click node_env "https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/env.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_client_entry,node_app_router,node_home,node_verify,node_chat,node_map,node_demo,node_theme,node_auth_hook toneBlue
class node_server_router,node_trpc,node_context,node_system,node_oauth,node_cookies,node_forge toneAmber
class node_notify,node_sdk,node_storage,node_storage_proxy,node_env toneMint
class node_database,node_schema toneRose
class node_user toneIndigo
```

## Components

### Web client

- [Client bootstrap](https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/main.tsx): `client/src/main.tsx`
- [App routes](https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Home experience](https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/pages/Home.tsx): `client/src/pages/Home.tsx`
- [Verification page](https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/pages/Verify.tsx): `client/src/pages/Verify.tsx`
- [AI chat](https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/components/AIChatBox.tsx): `client/src/components/AIChatBox.tsx`
- [Map view](https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/components/Map.tsx): `client/src/components/Map.tsx`
- [Demo data](https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/lib/ribat-demo.ts): `client/src/lib/ribat-demo.ts`
- [Theme context](https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/contexts/ThemeContext.tsx): `client/src/contexts/ThemeContext.tsx`
- [Client auth hook](https://github.com/jlassisamer/ribat-4hack/blob/main/client/src/_core/hooks/useAuth.ts): `client/src/_core/hooks/useAuth.ts`

### API and auth

- [API router](https://github.com/jlassisamer/ribat-4hack/blob/main/server/routers.ts): `server/routers.ts`
- [tRPC procedures](https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/trpc.ts): `server/_core/trpc.ts`
- [Request context](https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/context.ts): `server/_core/context.ts`
- [System endpoints](https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/systemRouter.ts): `server/_core/systemRouter.ts`
- [OAuth flow](https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/oauth.ts): `server/_core/oauth.ts`
- [Session cookies](https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/cookies.ts): `server/_core/cookies.ts`

### Platform services

- [Owner notifications](https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/notification.ts): `server/_core/notification.ts`
- [Platform SDK](https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/sdk.ts): `server/_core/sdk.ts`
- [Storage helpers](https://github.com/jlassisamer/ribat-4hack/blob/main/server/storage.ts): `server/storage.ts`
- [Storage proxy](https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/storageProxy.ts): `server/_core/storageProxy.ts`
- [Environment config](https://github.com/jlassisamer/ribat-4hack/blob/main/server/_core/env.ts): `server/_core/env.ts`

### Persistence

- [User database](https://github.com/jlassisamer/ribat-4hack/blob/main/server/db.ts): `server/db.ts`
- [User schema](https://github.com/jlassisamer/ribat-4hack/blob/main/drizzle/schema.ts): `drizzle/schema.ts`

### Other components

- **Visitor**
- **Forge storage API**

## Connections

- Visitor → Client bootstrap: opens app
- Client bootstrap → App routes: renders (evidence: `client/src/main.tsx`)
- App routes → Home experience: routes to (evidence: `client/src/App.tsx`)
- App routes → Verification page: routes to (evidence: `client/src/App.tsx`)
- App routes → Theme context: provides theme (evidence: `client/src/App.tsx`)
- Client bootstrap → API router: calls API (evidence: `client/src/main.tsx`)
- API router → tRPC procedures: registers procedures (evidence: `server/routers.ts`)
- API router → System endpoints: mounts (evidence: `server/routers.ts`)
- System endpoints → tRPC procedures: uses procedures (evidence: `server/_core/systemRouter.ts`)
- System endpoints → Owner notifications: notifies owner (evidence: `server/_core/systemRouter.ts`)
- tRPC procedures → Request context: builds context (evidence: `server/_core/trpc.ts`)
- Request context → Platform SDK: uses (evidence: `server/_core/context.ts`)
- Request context → User database: reads user data
- OAuth flow → User database: persists users (evidence: `server/_core/oauth.ts`)
- OAuth flow → Session cookies: manages session (evidence: `server/_core/oauth.ts`)
- OAuth flow → Platform SDK: uses (evidence: `server/_core/oauth.ts`)
- User database → User schema: queries schema (evidence: `server/db.ts`)
- Platform SDK → User database: uses (evidence: `server/_core/sdk.ts`)
- Owner notifications → Environment config: reads config (evidence: `server/_core/notification.ts`)
- Storage helpers → Environment config: reads config (evidence: `server/storage.ts`)
- Storage helpers → Forge storage API: requests presigned URLs (evidence: `server/storage.ts`)
- Storage proxy → Forge storage API: requests signed URLs (evidence: `server/_core/storageProxy.ts`)
- Storage proxy → Environment config: reads config (evidence: `server/_core/storageProxy.ts`)