# clyne-ui/vrom architecture

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

- Interactive diagram: https://gitdiagram.com/clyne-ui/vrom
- Repository: https://github.com/clyne-ui/vrom

## Overview

Vrom is a mobility-and-commerce platform with rider/customer operations, marketplace transactions, spatial matching, and an operations control center. The principal runtime flow is client requests through the Go HTTP server into domain handlers and persistent data; the admin console also calls backend endpoints for operational views and controls. Separate services provide spatial matching, AI capabilities, and Kafka stream analytics. The README contains no architecture detail, so several subsystem connections are shown only where source establishes them; unsampled integrations are omitted or marked unverified.

Main entry points: [`vrom/backend/cmd/vrom/main.go`](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/cmd/vrom/main.go) (HTTP API Server), [`vrom/backend/internal/api/http/shop_handler.go`](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/http/shop_handler.go) (Marketplace), [`vrom/backend/internal/services/auth_service.go`](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/services/auth_service.go) (Token Service), [`vrom/backend/internal/repository/database.go`](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/repository/database.go) (PostgreSQL Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Admin Console"]
  node_admin["Operations UI<br/>[page.tsx]"]
  node_api_client["Admin API Client<br/>[api-client.ts]"]
  node_admin_ops["Admin Workspaces"]
end

subgraph group_backend["Go Platform"]
  node_api_server["HTTP API Server<br/>[main.go]"]
  node_auth["Authentication<br/>[auth_handler.go]"]
  node_auth_tokens["Token Service<br/>[auth_service.go]"]
  node_auth_middleware["Access Middleware<br/>[auth.go]"]
  node_occ["Operations Control<br/>[occ_handler.go]"]
  node_websocket["Live Updates<br/>[handler.go]"]
  node_database[("PostgreSQL Store<br/>[database.go]")]
end

subgraph group_domain["Mobility Commerce"]
  node_commerce["Marketplace<br/>[shop_handler.go]"]
  node_orders["Orders &amp; Trips<br/>[order.go]"]
  node_riders["Rider Operations<br/>[rider_handler.go]"]
  node_spatial_api["Spatial API<br/>[spatial_handler.go]"]
  node_payments["Payments<br/>[payment_service.go]"]
  node_media["Media Uploads<br/>[media_service.go]"]
end

subgraph group_services["Intelligence Services"]
  node_matching["Spatial Matcher<br/>[main.rs]"]
  node_ai_service["AI Service<br/>[main.py]"]
end

subgraph group_analytics["Event Analytics"]
  node_events["Event Producer<br/>[producer.go]"]
  node_fraud["Fraud Detection"]
  node_surge["Surge Pricing"]
end

node_admin_user(("Admin"))
node_platform_user(("Platform User"))
node_kafka["Kafka"]
node_redis[("Redis")]

node_admin_user -->|"uses"| node_admin
node_admin -.->|"requests data"| node_api_client
node_api_client -.->|"calls endpoints"| node_api_server
node_api_server -->|"routes auth"| node_auth
node_api_server -->|"routes operations"| node_occ
node_api_server -->|"routes commerce"| node_commerce
node_api_server -->|"wraps protected routes"| node_auth_middleware
node_auth -->|"issues tokens"| node_auth_tokens
node_auth_middleware -.->|"validates tokens"| node_auth_tokens
node_auth_tokens -->|"checks revocation"| node_redis
node_commerce -.->|"queries data"| node_database
node_occ -.->|"reads operations data"| node_database
node_spatial_api -.->|"requests matches"| node_matching
node_platform_user -.->|"uses platform"| node_api_server
node_api_server -->|"starts hub"| node_websocket
node_api_server -->|"connects database"| node_database
node_commerce -.->|"uploads media"| node_media
node_orders -.->|"uses payment service"| node_payments
node_events -.->|"publishes events"| node_kafka
node_kafka -.->|"consumes transactions"| node_fraud
node_kafka -.->|"consumes events"| node_surge

click node_admin "https://github.com/clyne-ui/vrom/blob/main/vrom/vrom-admin/app/dashboard/page.tsx"
click node_api_client "https://github.com/clyne-ui/vrom/blob/main/vrom/vrom-admin/lib/api-client.ts"
click node_admin_ops "https://github.com/clyne-ui/vrom/tree/main/vrom/vrom-admin/app/dashboard"
click node_api_server "https://github.com/clyne-ui/vrom/blob/main/vrom/backend/cmd/vrom/main.go"
click node_auth "https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/http/auth_handler.go"
click node_auth_tokens "https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/services/auth_service.go"
click node_auth_middleware "https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/middleware/auth.go"
click node_occ "https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/http/occ_handler.go"
click node_websocket "https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/websocket/handler.go"
click node_database "https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/repository/database.go"
click node_commerce "https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/http/shop_handler.go"
click node_orders "https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/repository/order.go"
click node_riders "https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/http/rider_handler.go"
click node_spatial_api "https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/http/spatial_handler.go"
click node_payments "https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/services/payment_service.go"
click node_media "https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/services/media_service.go"
click node_matching "https://github.com/clyne-ui/vrom/blob/main/vrom/matching_engine/src/main.rs"
click node_ai_service "https://github.com/clyne-ui/vrom/blob/main/vrom/ai_service/main.py"
click node_events "https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/events/producer.go"
click node_fraud "https://github.com/clyne-ui/vrom/blob/main/vrom/stream_processor/src/main/java/com/vrom/stream/FraudDetectionJob.java"
click node_surge "https://github.com/clyne-ui/vrom/blob/main/vrom/stream_processor/src/main/java/com/vrom/stream/SurgePricingJob.java"

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_admin,node_api_client,node_admin_ops,node_platform_user toneBlue
class node_api_server,node_auth,node_auth_tokens,node_auth_middleware,node_occ,node_websocket,node_database,node_redis toneAmber
class node_commerce,node_orders,node_riders,node_spatial_api,node_payments,node_media toneMint
class node_matching,node_ai_service toneRose
class node_events,node_fraud,node_surge,node_admin_user,node_kafka toneIndigo
```

## Components

### Admin Console

- [Operations UI](https://github.com/clyne-ui/vrom/blob/main/vrom/vrom-admin/app/dashboard/page.tsx): `vrom/vrom-admin/app/dashboard/page.tsx`
- [Admin API Client](https://github.com/clyne-ui/vrom/blob/main/vrom/vrom-admin/lib/api-client.ts): `vrom/vrom-admin/lib/api-client.ts`
- [Admin Workspaces](https://github.com/clyne-ui/vrom/tree/main/vrom/vrom-admin/app/dashboard): `vrom/vrom-admin/app/dashboard`

### Go Platform

- [HTTP API Server](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/cmd/vrom/main.go): `vrom/backend/cmd/vrom/main.go`
- [Authentication](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/http/auth_handler.go): `vrom/backend/internal/api/http/auth_handler.go`
- [Token Service](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/services/auth_service.go): `vrom/backend/internal/services/auth_service.go`
- [Access Middleware](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/middleware/auth.go): `vrom/backend/internal/api/middleware/auth.go`
- [Operations Control](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/http/occ_handler.go): `vrom/backend/internal/api/http/occ_handler.go`
- [Live Updates](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/websocket/handler.go): `vrom/backend/internal/api/websocket/handler.go`
- [PostgreSQL Store](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/repository/database.go): `vrom/backend/internal/repository/database.go`

### Mobility Commerce

- [Marketplace](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/http/shop_handler.go): `vrom/backend/internal/api/http/shop_handler.go`
- [Orders & Trips](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/repository/order.go): `vrom/backend/internal/repository/order.go`
- [Rider Operations](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/http/rider_handler.go): `vrom/backend/internal/api/http/rider_handler.go`
- [Spatial API](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/api/http/spatial_handler.go): `vrom/backend/internal/api/http/spatial_handler.go`
- [Payments](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/services/payment_service.go): `vrom/backend/internal/services/payment_service.go`
- [Media Uploads](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/services/media_service.go): `vrom/backend/internal/services/media_service.go`

### Intelligence Services

- [Spatial Matcher](https://github.com/clyne-ui/vrom/blob/main/vrom/matching_engine/src/main.rs): `vrom/matching_engine/src/main.rs`
- [AI Service](https://github.com/clyne-ui/vrom/blob/main/vrom/ai_service/main.py): `vrom/ai_service/main.py`

### Event Analytics

- [Event Producer](https://github.com/clyne-ui/vrom/blob/main/vrom/backend/internal/events/producer.go): `vrom/backend/internal/events/producer.go`
- [Fraud Detection](https://github.com/clyne-ui/vrom/blob/main/vrom/stream_processor/src/main/java/com/vrom/stream/FraudDetectionJob.java): `vrom/stream_processor/src/main/java/com/vrom/stream/FraudDetectionJob.java`
- [Surge Pricing](https://github.com/clyne-ui/vrom/blob/main/vrom/stream_processor/src/main/java/com/vrom/stream/SurgePricingJob.java): `vrom/stream_processor/src/main/java/com/vrom/stream/SurgePricingJob.java`

### Other components

- **Admin**
- **Platform User**
- **Kafka**
- **Redis**

## Connections

- Admin → Operations UI: uses (evidence: `vrom/vrom-admin/app/dashboard/page.tsx`)
- Operations UI → Admin API Client: requests data
- Admin API Client → HTTP API Server: calls endpoints
- HTTP API Server → Authentication: routes auth (evidence: `vrom/backend/cmd/vrom/main.go`)
- HTTP API Server → Operations Control: routes operations (evidence: `vrom/backend/cmd/vrom/main.go`)
- HTTP API Server → Marketplace: routes commerce (evidence: `vrom/backend/cmd/vrom/main.go`)
- HTTP API Server → Access Middleware: wraps protected routes (evidence: `vrom/backend/cmd/vrom/main.go`)
- Authentication → Token Service: issues tokens (evidence: `vrom/backend/internal/api/http/auth_handler.go`)
- Access Middleware → Token Service: validates tokens
- Token Service → Redis: checks revocation (evidence: `vrom/backend/internal/services/auth_service.go`)
- Marketplace → PostgreSQL Store: queries data
- Operations Control → PostgreSQL Store: reads operations data
- Spatial API → Spatial Matcher: requests matches
- Platform User → HTTP API Server: uses platform
- HTTP API Server → Live Updates: starts hub (evidence: `vrom/backend/cmd/vrom/main.go`)
- HTTP API Server → PostgreSQL Store: connects database (evidence: `vrom/backend/cmd/vrom/main.go`)
- Marketplace → Media Uploads: uploads media
- Orders & Trips → Payments: uses payment service
- Event Producer → Kafka: publishes events
- Kafka → Fraud Detection: consumes transactions
- Kafka → Surge Pricing: consumes events
