Viana API¶
A ride-hailing backend built for real-time scale.
Viana is a Spring Boot monolith exposing a REST + WebSocket API for coordinating customers, drivers, and rides in real time. This documentation covers everything — architecture, authentication, every endpoint, WebSocket topics, and data models.
What's inside¶
-
Getting Started
Prerequisites, environment variables, and running the stack locally.
-
Architecture
How ride matching, real-time location, and async timers fit together.
-
Authentication
JWT access tokens, refresh token rotation, role-based access.
-
API Reference
Every REST endpoint with request/response schemas and examples.
-
WebSocket Reference
STOMP connection setup, all topics, and message payloads.
-
Data Models
All entities, enums, and database relationships.
Stack at a glance¶
| Layer | Technology |
|---|---|
| Runtime | Java 21, Spring Boot 3.5.5 |
| Auth | Stateless JWT (jjwt 0.11.5), refresh token rotation |
| Database | PostgreSQL 15 + PostGIS 3.3 (JPA/Hibernate Spatial) |
| Cache / Geo | Redis 7 (Geo commands via Lettuce) |
| Real-time | STOMP over SockJS, SimpMessagingTemplate |
| File storage | AWS S3 (LocalStack for local dev) |
| Async | ThreadPoolTaskExecutor + Reactor Mono.delay |
| Observability | Spring Actuator + Prometheus |
Base URL¶
http://localhost:8080
All REST endpoints are prefixed with /api unless documented otherwise.
All protected endpoints require Authorization: Bearer <access_token>.