Technical Architecture

See the Diagrams page for the deployment diagram. See the Functional Overview for goals, context, and users.

1. Building Block View

REV Spain is a monolith. Main internal modules:

• Intake module — claimant onboarding and document/data submission entry point
• Extraction engine — parses ITA and RNT documents (fixed-structure official Spanish government PDFs) using direct PDF text extraction (no OCR, since layout is standardized)
• Unified.to adapter — alternative ingestion path fetching employee/salary data directly from client HR/payroll systems
• Project & employee allocation module — gathers project information and maps employees to projects
• Eligibility rules engine — evaluates R&D tax credit eligibility criteria
• Report generator — produces both financial and technical claim reports
• Access control — role-based access for claimants, reviewers, and admins

2. Deployment View

Stack

• Frontend: Vue.js 3 SPA
• Backend: Node.js / Express API
• Data & document storage: MongoDB, including GridFS for document storage (no separate object storage service)

Topology

• VM 1 — runs the full application stack via Docker Compose (frontend, API, MongoDB)
• VM 2 — reverse proxy handling the domain name and TLS termination, forwarding to VM 1

This is a single-server deployment: no horizontal scaling or failover across app instances currently exists.

3. Risks & Technical Debt

• Single point of failure — the entire application stack (including the database) runs on one VM; no redundancy or failover.
• No documented scaling path — current architecture sits in tension with quality goals like fast data gathering and claims centralization at higher volume.
• Shared storage engine — MongoDB serves both transactional data and GridFS document storage; document I/O could contend with regular query load as usage grows.
• External dependency — the Unified.to ingestion path introduces availability dependency on a third party for one of the two data-gathering flows.
• PII handling — sensitive employee/salary data is processed directly by the core system in both ingestion paths; encryption, access control, and retention policies should be explicitly reviewed and documented.