Skip to Content
Ranlanka CRM documentation — pre-release, subject to change.
Architecture

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 → Entity

Cross-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_at column 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 (validate mode). Every schema change is a new V<n>__description.sql file under db/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 the roles/role_permissions tables 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 Nginx limit_req_zone. The application uses server.forward-headers-strategy=framework to 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 forced Content-Disposition: attachment headers. When documents are deleted from the UI, objects in R2 are automatically renamed with a deleted_ 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):

JobSchedulePurposeManual Trigger API
DailyDigestScheduler0 0 19 * * * (19:00 Asia/Colombo)Daily summary email of new visas, flights, tours, and financial totals with CSV attachment sent to owners/managersPOST /api/v1/reminder-settings/trigger-daily-digest
DailyApprovedVisaScheduler0 30 4 * * * (10:00 Asia/Colombo)Daily morning manifest email of uncollected approved visas older than 7 daysPOST /api/v1/reminder-settings/trigger-approved-visa-digest
WeeklyDigestScheduler0 0 20 * * SUN (Sun 20:00 Asia/Colombo)Weekly digest email of the preceding 7 days of bookings, revenue, and pending tasksPOST /api/v1/reminder-settings/trigger-weekly-digest
MonthlyDigestScheduler0 0 8 1 * * (1st of month 08:00 Asia/Colombo)Comprehensive monthly summary email with Apache POI multi-sheet Excel workbook attachmentPOST /api/v1/reminder-settings/trigger-monthly-digest
ReminderSchedulerService0 0 8 * * * (08:00 daily)Automated lead-time reminders for visa expirations, flight departures, and recurring bill due datesPOST /api/v1/reminder-settings/run-now
DocumentCleanupService0 0 4 * * * (04:00 daily)Permanently purges soft-deleted documents (deleted_at > 30 days) from Cloudflare R2 and PostgreSQLAutomated cron
QuoteCleanupService0 0 3 * * * (03:00 daily)Soft-deletes unaccepted quotations past their 3-day validity windowAutomated 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 alloy shipper, toggled by a Compose profile.

See Security for the auth model and permission system.

Last updated on