Architecture
An overview of how Ranlanka CRM is structured, for anyone extending or
operating the app. For line-level internal notes, see KNOWLEDGE_BASE.md in
the project root — this page is the readable summary of that file.
Repo layout
Two independent repos, developed side by side but deployed separately:
- Spring Boot 3.5 · Java 23 backend
- React 19 · Vite frontend
Each has its own git history, CI/CD, and pre-commit hooks — there is no shared
root repo or shared package.json.
System Architecture Diagram
Document Storage & Lifecycle Flow
All uploaded files (customer identity documents, passports, visa copies, flight tickets, and receipts) follow a secure, annotated lifecycle between the React frontend, Spring Boot backend, and Cloudflare R2 object storage:
Backend
A modular monolith: every business domain is its own module under
modules/* (staff, customer, booking, lead, finance, accounting,
quotation, checklist, dashboard, reference, auth, utility), each following the
same layering:
Controller → Service → Repository → EntityCross-cutting concerns (security, email, scheduling, file storage, logging)
live in shared/* and are used by every module.
Conventions
- IDs are UUIDs, generated by Postgres (
gen_random_uuid()), never by the application. - Soft deletes — most entities carry a
deleted_atcolumn and a@SQLRestriction("deleted_at IS NULL")annotation, so deleted rows are filtered out of every query automatically. - Schema changes are migration-only — Hibernate’s DDL auto-generation is
disabled (
validatemode). Every schema change is a newV<n>__description.sqlfile underdb/migration/, applied by Flyway on startup. - RBAC is database-backed, not a Java enum — permission strings (e.g.
VISA_CREATE,INVOICE_CANCEL,REMINDER_SETTINGS_MANAGE) live in theroles/role_permissionstables and are checked via@PreAuthorize("hasAuthority('X')"). - Uniform API responses — every controller returns
ApiResponse<T>. - Rate Limiting — API endpoints are protected by
RateLimitingFilter, enforcing a 100 req/min sliding window and returning an HTTP 429 response on limit exceeded. This works alongside Nginxlimit_req_zone. The application usesserver.forward-headers-strategy=frameworkto properly resolve client IPs. - Statistics Matrix Endpoints — Dedicated backend endpoints compute multi-attribute breakdowns:
/api/v1/visas/stats-matrix,/api/v1/flights/stats-matrix, and/api/v1/tours/stats-matrix. - Cloudflare R2 Object Storage (
R2FileStorageServiceImpl) — All uploaded customer files, visas, tickets, and identity documents are stored in Cloudflare R2 S3-compatible buckets (ranlanka-crm/ranlanka-crm-dev). Files use deterministic hierarchical keys (customers/{id}/...) and are served via presigned URLs with forcedContent-Disposition: attachmentheaders. When documents are deleted from the UI, objects in R2 are automatically renamed with adeleted_prefix, and permanently purged after a 30-day retention window. - Dynamic Reference & Country Data — Categories like
COUNTRY,VISA_TYPE,ENTRY_TYPE,JOB_TITLE, etc., are stored in the database (lookup_values) and administered through Admin Data → Reference Data (/admin/lookup-values). Nationality and destination dropdowns across all customer, service, and onboarding forms dynamically pull from this dataset.
Scheduled jobs & automation engine
Seven scheduled cron jobs run in-process (managed by Spring’s @Scheduled and TaskScheduler):
| Job | Schedule | Purpose | Manual Trigger API |
|---|---|---|---|
DailyDigestScheduler | 0 0 19 * * * (19:00 Asia/Colombo) | Daily summary email of new visas, flights, tours, and financial totals with CSV attachment sent to owners/managers | POST /api/v1/reminder-settings/trigger-daily-digest |
DailyApprovedVisaScheduler | 0 30 4 * * * (10:00 Asia/Colombo) | Daily morning manifest email of uncollected approved visas older than 7 days | POST /api/v1/reminder-settings/trigger-approved-visa-digest |
WeeklyDigestScheduler | 0 0 20 * * SUN (Sun 20:00 Asia/Colombo) | Weekly digest email of the preceding 7 days of bookings, revenue, and pending tasks | POST /api/v1/reminder-settings/trigger-weekly-digest |
MonthlyDigestScheduler | 0 0 8 1 * * (1st of month 08:00 Asia/Colombo) | Comprehensive monthly summary email with Apache POI multi-sheet Excel workbook attachment | POST /api/v1/reminder-settings/trigger-monthly-digest |
ReminderSchedulerService | 0 0 8 * * * (08:00 daily) | Automated lead-time reminders for visa expirations, flight departures, and recurring bill due dates | POST /api/v1/reminder-settings/run-now |
DocumentCleanupService | 0 0 4 * * * (04:00 daily) | Permanently purges soft-deleted documents (deleted_at > 30 days) from Cloudflare R2 and PostgreSQL | Automated cron |
QuoteCleanupService | 0 0 3 * * * (03:00 daily) | Soft-deletes unaccepted quotations past their 3-day validity window | Automated cron |
All jobs are stateless across restarts — deduplication logs and per-job toggle configurations live in PostgreSQL (reminder_send_log, reminder_settings), and can be triggered on-demand with custom date windows via the Admin Data → Triggers UI (/admin/triggers).
PDF & email rendering
No templating engine — HTML for both PDFs and emails uses plain
{{PLACEHOLDER}} string substitution on .html files. PDFs are rendered via
openhtmltopdf, which does not support CSS flexbox — layouts in the three
PDF templates (invoice, quote, receipt) use block/table layout instead. Company contact coordinates (app.company.*) are injected dynamically into header and footer blocks.
Frontend
React 19 + Vite, Redux Toolkit for state, Tailwind CSS v4 for styling
(@theme custom properties, with a :root.dark override block for dark
mode). Routing via react-router-dom. Features a dedicated Admin Data suite for Reference Data, Reminder Settings, Trigger Management, and Audit Trail.
Deployment
- Backend ships as a Docker image (multi-stage build, non-root user),
published to Docker Hub via GitHub Actions on push to
main. - Database is Supabase-hosted Postgres — no local Postgres container in the deploy compose file.
- Hosting is a single Oracle Cloud “Always Free” instance, deployed via a manual-trigger GitHub Actions workflow.
- Logging ships to Grafana Cloud’s hosted Loki via an
alloyshipper, toggled by a Compose profile.
See Security for the auth model and permission system.