PURPOSE & SCOPE

This document describes the actual production architecture behind YARBIS as of September 2026 — not a target-state design. It is maintained as the platform evolves; sections marked "planned" describe committed roadmap items, not live capabilities.

COMPUTE & ORCHESTRATION

Host Environment

YARBIS runs on a single VPS: Ubuntu 24.04.5 LTS, kernel 6.8.0-139-generic, x86_64, 4-core AMD EPYC 7543P, 15GB RAM, 16TB storage. This is a single-host deployment, not a multi-node cluster.

Container Runtime

Docker Engine 29.8.1 is the sole runtime. Each tenant and each shared service is defined as its own Docker Compose stack rather than one shared compose file — per-tenant docker-compose.yml definitions ranging 5–11KB depending on service count. As of this writing the host runs 80 active containers across 11 tenants plus shared infrastructure services, with zero orphaned volumes, zero unused images, and zero stopped containers left uncleaned.

Orchestration Model

There is no Kubernetes or Swarm orchestrator in production. Single-host Compose keeps operational complexity bounded at current scale while preserving a direct migration path: every service is already a discrete, externally-configured container rather than a monolith, which is the precondition for a future orchestrator migration, not a substitute for one.

NETWORKING & INGRESS

Edge Layer

Traefik v3.6.7 is the platform's sole ingress point, running as a Layer 7 reverse proxy with the Docker provider enabled for dynamic service discovery. Routing rules attach to containers via Docker labels rather than static config files — a new tenant's routes go live as soon as its container starts, with no reload of Traefik's own configuration.

TLS

TLS is terminated at Traefik. Certificates are issued and renewed automatically via the ACME/Let's Encrypt HTTP-01 challenge (confirmed via active certificate stores on the host).

Static Asset Delivery

Each tenant runs its own dedicated Nginx container scoped specifically to static asset and media delivery, separate from routing (Traefik) and application logic (Odoo). This division keeps each layer independently scalable and simpler to reason about.

Tenant Network Segmentation

Each tenant's containers run on their own isolated Docker bridge network (confirmed: 11 tenant-scoped networks currently active, each attaching only that tenant's own services). Traefik is the only component with a path across network boundaries, acting as the single controlled crossing point between the public internet and any tenant's internal services.

DATA LAYER & MULTI-TENANCY

Isolation Model

Multi-tenancy is enforced at the infrastructure level, not the application level: each tenant runs its own dedicated PostgreSQL 15 container rather than a shared instance with schema- or row-level tenant scoping. A query bug or a compromised application layer in one tenant's Odoo instance cannot reach another tenant's data at the database engine level — a guarantee schema-based multi-tenancy does not give to the same degree.

Tradeoff

The cost of this model is per-tenant resource overhead — a dedicated Postgres process and memory footprint per tenant instead of one shared instance. At the platform's current scale (11 tenants) that tradeoff favors isolation over density.

Transactional Integrity

PostgreSQL provides ACID guarantees for all transactional and financial data processed through Odoo.

AI / DOCUMENT INTELLIGENCE INFRASTRUCTURE

Current State

pgvector is installed and available as a PostgreSQL extension on the platform, but it is not currently in active use. There is no semantic search, embeddings-based retrieval, or vector similarity search running in production today.

Document Storage Today

Document storage and retrieval — PDFs, images, identity documents, financial statements — runs entirely through Odoo's native Attachment model. Files are stored as standard ir.attachment records tied to their parent record (a borrower or loan file) via res_model/res_id, and inherit that record's access control rules rather than being governed by a separate document-access layer.

Planned Direction

pgvector represents provisioned infrastructure for a future AI-assisted document retrieval layer. When implemented, the tenant isolation model described above will need to be extended to the vector store explicitly — at present, pgvector runs as a single shared instance rather than one per tenant, so isolation there is an open design question to resolve before, not after, that capability goes live.

AUTOMATION & INTEGRATION LAYER

n8n

n8n orchestrates webhook processing, API integrations, and workflow automation. Each tenant runs its own dedicated n8n instance and its own n8n Postgres database — automation logic, credentials, and webhook endpoints for one tenant are not reachable from another tenant's instance.

Production Workflows

Automated workflows currently in production include borrower onboarding (Borrower Discovery), document routing (OCR/document viewer), and Letters of Explanation generation and e-signature routing.

APPLICATION LAYER (ODOO / ERP)

System of Record

Odoo 18 Community Edition is the transactional system of record for CRM, pipeline tracking, and accounting. Each tenant runs its own dedicated Odoo container and database — no shared Odoo instance across tenants.

Custom Modules

YARBIS-specific functionality (Borrower Discovery, Update Borrower, the Document Viewer, the Loan Pipeline Menu, the LOE/DocuSeal integration) is built as custom Odoo modules and embedded HTML components served alongside the core Odoo instance, integrated via n8n webhooks rather than modifying Odoo core.

DOCUMENT PROCESSING & E-SIGNATURE

DocuSeal

DocuSeal (self-hosted, Community edition) handles e-signature workflows for the 15 Letters of Explanation templates, with its own dedicated Postgres and Redis containers per the yarbis tenant's stack.

Gotenberg

Gotenberg handles server-side document generation/conversion (e.g., producing signable PDFs from templated content) ahead of the DocuSeal signing step.

COMMUNICATIONS INFRASTRUCTURE

Email

Mailcow provides self-hosted email infrastructure, with SPF, DKIM, and DMARC configured for deliverability and domain reputation.

Messaging

Evolution API provides WhatsApp/SMS integration, governed by the SMS/WhatsApp/TCPA Consent Framework published in the Legal Framework section of this site.

Scheduling

Cal.com handles appointment scheduling and calendar coordination for lender and agent workflows, running as its own dedicated service with its own database.

ACCESS CONTROL & IDENTITY

Current Model

Access control today runs on Odoo's native user and group permission model: each user is assigned to functional groups (loan officer, administrator, borrower-facing, etc.) that gate which records and actions they can reach, inherited automatically by every custom module built on top of Odoo.

Roadmap

Multi-factor authentication and a formally documented, granular role-based access policy beyond Odoo's default groups are on the platform's security hardening roadmap, to be layered on as the client base and the number of administrative users grow.

HOST & TRANSPORT SECURITY

Host Hardening

SSH key-based authentication, Fail2ban, and a UFW firewall are active on the host, with security patches current as of the last diagnostic (zero pending security updates).

Transport Encryption

All web-facing traffic is encrypted via TLS, terminated at Traefik with automated certificate issuance and renewal.

Isolation as a Security Control

Per-tenant Docker network segmentation (see Networking & Ingress) is the platform's primary control against lateral movement between tenants — a compromise in one tenant's application layer does not have a network path to another tenant's containers.

OBSERVABILITY (PLANNED)

Status

A full-stack observability layer — Prometheus (metrics), Grafana (dashboards), Loki (log aggregation), Netdata (real-time infrastructure telemetry), and Uptime Kuma (external availability monitoring) — is part of YARBIS's finalized technical roadmap. It has not yet been deployed to production; current operational visibility relies on direct infrastructure diagnostics rather than automated dashboards.

Design Intent

Once deployed, this stack is intended to give continuous, automated visibility into infrastructure health, traffic patterns, latency, logs, and per-tenant service uptime, replacing manual diagnostics.

DEPLOYMENT & RELEASE

Current Process

Deployments run directly against each tenant's Docker Compose stack: images are rebuilt and containers restarted following a rolling-deployment approach, without an automated build/test pipeline in front of it today.

Roadmap

A formal release process — a staging environment, an automated CI/CD pipeline, and a documented rollback procedure — is the near-term engineering milestone for standardizing releases as tenant count and release frequency increase.

BACKUP & DISASTER RECOVERY

Current State

A full VPS-level backup runs daily at 2:00 AM CST, covering every tenant container, database, and configuration file on the host.

Gap and Direction

Formal disaster recovery — a documented, tested procedure with a defined recovery time objective, built on top of that backup — is not yet in place. The direction already set for closing that gap is infrastructure replication: a second, geographically separate VPS kept in sync as a standby target, so a host-level failure is recovered onto already-replicated infrastructure rather than rebuilt from a cold backup. Daily backups are today's safety net; replicated infrastructure is the next milestone on top of it.

SCALABILITY & ARCHITECTURAL EVOLUTION

Current Ceiling

The architecture scales today by adding tenants within the existing single-host Compose model. At 80 containers on a 4-core/15GB host, headroom exists but is finite — the host, not the architecture, is the current scaling constraint.

Next Steps

The two changes that extend this ceiling, in order: (1) infrastructure replication for disaster recovery, which also creates a second host that can absorb load; (2) migration to container orchestration (Kubernetes-compatible by design, per the container-per-service model already in place) once tenant count or availability requirements justify that operational overhead.