Architecture and security
What the system is made of and what protects it — in plain words, without a technical dictionary.
You do not need to know most of this to work in the system. But when something gets stuck it helps to know where things happen — why a price is computed on the server, why one company’s data cannot leak into another, and why some changes appear at once while others wait for a new app version.
System parts
| Part | Technology | Purpose |
|---|---|---|
| API | NestJS + Prisma | One server for every channel; prefix /api |
| Database | PostgreSQL + PostGIS | Data of all companies, per-company RLS, zone geometry |
| Rate-limit store | Redis | Request counting per key and per address |
| Web channels | No framework, static | Company console, driver and passenger web, platform console |
| Apps | Flutter (Android, iOS) | Driver and passenger app under the company brand |
| Files | S3-kompatibilna pohrana (R2) | Fleet and company documents; only the key stays in the database |
| Maps | Mapbox, Google, OSRM | Map, addresses and routing; the provider is a company setting |
| Payments | Stripe, Nexi, Viva.com | In-app card payment and SoftPOS on a terminal |
| Fiscalisation | CIS (HR), e-invoice | Fiscal receipt according to country rules |
| Push | FCM (Android), APNs (iOS) | Notifications to drivers and passengers |
Sessions and sign-in
- Sign-in returns a short-lived access token and a refresh token; the refresh token is issued once and rotates on every use.
- Passwords follow rules checked on both client and server; the owner’s first password is temporary and must be changed.
- Two-factor sign-in (TOTP) is available on platform accounts; a sign-in without the second factor does not receive a token.
- Every change of security-sensitive data ends up in the audit log with the user, time and address.
Rate limits
| What | Limit | Source |
|---|---|---|
| All requests (default) | 120 per 60 seconds | api/src/app.module.ts |
Partner API /api/v1 | 120 per minute per key | api-v1.controller.ts |
| Sign-in and password reset | stricter, per address and account | auth/* |
When a limit is exceeded the response is 429 with the code errors.tooManyRequests and a Retry-After header. A client that retries must honour that header — otherwise it only extends the block.
Real-time events
There are three event channels (Server-Sent Events). All are one-way: the server sends, the client listens.
| Channel | For | Carries |
|---|---|---|
GET /api/driver/events/stream | Driver app | New offers, ride changes, dispatcher messages |
GET /api/company/events/stream | Company console | New rides, status changes, driver arrivals |
GET /api/public/rides/:token/events | Passenger tracking page | Vehicle position and ride status for one token |
One error shape
Every error, whether from field validation or from a business rule, has the same shape. message is for humans, key is for code — and key is never translated.
{
"statusCode": 400,
"message": "Ovaj modul nije uključen za tvrtku.",
"key": "errors.moduleDisabled",
"locale": "hr"
}
The catalogue contains 739 distinct error keys in the code. The most important ones, with translation and HTTP status, are on the Errors and limits page.
Isolation and audit
tenantIdis never read from a request; it comes from the session or from the API key.- PostgreSQL RLS is the second layer: a query without company context returns nothing.
- The audit log records who changed what, when and from where — including platform actions on another company.
- Documents are not stored in the database: the database keeps the key, the content lives in private storage behind a signed link.
External providers
Providers are chosen by the company; the platform supports them without code changes. Keys live on the company’s server, and the console only shows whether a provider is connected.
| Area | Supported | Note |
|---|---|---|
| Maps and addresses | Mapbox, Google Maps, OSRM | Token per company; the public map token is separate from the secret one |
| Card payments | Stripe, Nexi, Viva.com | Webhook per provider; the signature is verified before booking |
| Fiscalisation | CIS (HR), e-invoice | Mode (test/production) is an explicit setting |
| Push | FCM, APNs | Configuration per company, not shared |
| SMTP | Templates per company, the sender is the company | |
| Telephony | PBX / pozivni centar | Number masking and call transfer; module addon.operator_console |