Technical Architecture

The Walled City

Every client environment is a fully isolated, independently deployable fortress — built on enterprise-grade infrastructure with Zero Trust security, automated provisioning, and continuous deployment.

The Metaphor

Why We Named It Lucca

Lucca is a Renaissance city in Tuscany, famous for its perfectly preserved walls. For centuries, those walls defined the boundary between the thriving, cultivated interior and the unpredictable world outside. Controlled gates regulated who entered and exited. The city flourished — not in spite of its walls, but because of them.

Our infrastructure layer is named after Lucca because every client gets their own walled city: separate code, separate data, separate secrets, separate domains — connected only by the control plane, Mocca.

This isn't multi-tenancy behind a shared wall. Each environment is its own independent deployment — its own repository, its own CI/CD pipeline, its own database, its own access policies. If one city falls, the others stand. That's the architecture.

Platform Overview

The Three-Layer Stack

The platform is composed of three named layers — each with a distinct responsibility, each independently scalable, all orchestrated from the control plane.

Deep Dive

Infrastructure Layers

🏰 Lucca — Infrastructure Fortress Provisioning & Security

Deployment Platform — Cloudflare Pages (with support for Vercel, AWS Amplify). Each project has its own Pages instance with automatic builds.
Git Repository — Private GitHub repository per project, generated from production-grade templates. Configurable organisation, template repo, production branch, staging branch.
Domains & DNS — Custom production and staging domains (e.g. crm.clientname.nz, crm-test.clientname.nz). Cloudflare zone management with automatic CNAME provisioning. Support for externally-managed DNS zones.
Zero Trust / Access — Cloudflare Access policies per application. JWT-validated access with team domain + Application AUD tags. Separate AUD tags for CRM and API applications. No VPNs, no open ports, no exposed attack surface.
Database & Storage — Neon Serverless PostgreSQL per environment (with Supabase, PlanetScale support planned). Configurable PG version (15/16/17). Schema migrations directory configurable per project. Optional R2 object storage bucket for file uploads.
Actions Secrets — Automated injection of secrets into GitHub repositories: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, NEON_API_KEY, MOCCA_WEBHOOK_SECRET (auto-generated per project). Secrets are injected at provisioning time and can be rotated.

💡 Every component is created programmatically via API — no manual setup, no configuration drift, no shared resources.

☕ Mocca — Operations Platform Control Plane

Multi-client, multi-project management from a single interface
Client and project CRM with milestones and tasks
Time tracking integrated with Xero invoicing
Document lifecycle — proposals, SOWs, contracts
Support ticketing and real-time chat
Infrastructure monitoring — deploy status, pipeline health, provisioned timestamps
Client portal management — provision and configure portals per client

☕ Mocca is the single pane of glass — every project, every deploy, every invoice, one interface.

🥛 Crema — Client Experience User-Facing Applications

Branded client portals — each client gets their own portal domain and identity
Custom CRM applications built per client workflow
Data dashboards from integrated sources
Document sharing and approval workflows

🥛 Every Crema instance is a unique product — same platform, different experience, zero interference.

Deployment Pipeline

Git → Deploy — The Full Pipeline

Every project follows the same deterministic path from template to production. No manual steps, no ad-hoc configuration, no snowflake environments.

Template Repository

One-Button Provision

Private GitHub Repo Created

Push to Branch

GitHub Actions CI/CD

Lint → Type-Check → Build

Staging Branch

Deploy to Staging

Main Branch

Deploy to Production

Webhook → Mocca Status Update

Template Cloning

New projects are created from battle-tested template repositories containing the full stack: frontend, API, database schema, CI/CD pipeline, infrastructure-as-code.

Automated Provisioning

One button creates: private repo, configures Actions secrets, sets up Pages project, provisions DNS, creates Zero Trust policies.

Branch Strategy

staging branch triggers test environment deploys. main branch triggers production deploys. Feature branches for development.

CI/CD Pipeline

GitHub Actions runs on every push: lint, type-check, build, deploy to Cloudflare Pages. Fully automated, zero manual intervention.

Webhook Integration

On deployment completion, Cloudflare/GitHub sends a webhook to Mocca, updating deploy status, timestamp, and stage in real-time.

Zero-Downtime Deploys

Cloudflare Pages uses atomic deployments. The old version serves traffic until the new build is fully uploaded, then switches instantly.

Security

Security Architecture

Security isn't a feature — it's the foundation. Every layer of the stack enforces isolation, encryption, and least-privilege access by default.

🔒 Network Isolation

Each client runs on their own Cloudflare Pages project. No shared compute, no shared database, no co-tenancy.

🛡️ Zero Trust Access

Every request authenticated via Cloudflare Access JWT. Team domain + AUD tag validation. No VPN required.

🔐 Encrypted Secrets

API tokens, database credentials, and webhook secrets are injected as sealed GitHub secrets. Never stored in code or logs.

🌐 Edge Security

All traffic routes through Cloudflare's global network. DDoS protection, WAF, bot management, and SSL termination at the edge.

🗄️ Database Isolation

Each client has their own Neon PostgreSQL database. Connection strings are per-environment secrets. No shared schemas.

📋 Audit Trail

Every deployment, configuration change, and provisioning event is logged with timestamp and actor.

No VPNs. No open ports. No shared databases. No co-tenancy. Every client is a fully isolated fortress — and we wouldn't build it any other way.

Provisioning

What Gets Provisioned

One button press triggers the creation of all of the following. Every component is API-driven, repeatable, and auditable.

Component	What's Created	Lifecycle
GitHub Repository	Private repo from template	Per-project, permanent
CI/CD Pipeline	GitHub Actions workflow	Automatic on push
Cloudflare Pages	Pages project + custom domains	Per-environment
DNS Records	CNAME records for prod + staging	Auto-provisioned
Zero Trust Policies	CF Access application + policies	Per-application
Database	Neon PostgreSQL instance	Per-environment
Object Storage	R2 bucket (optional)	Per-project
Secrets	4 GitHub Actions secrets	Injected at provision

Components Created

Button Press

Manual Steps

~2 min

Provision Time

Configuration

Infrastructure as Code

Every configuration value is stored in the project record inside Mocca. The Lucca Configuration panel lets operators define the entire infrastructure shape — and those values generate the actual infrastructure at provision time.

No YAML files. No Terraform state. The project record is the source of truth — and the infrastructure is generated from it.

Provider selection (Cloudflare, Vercel, AWS)

Git organisation and template

Branch strategy (staging + production)

Domain configuration

Zero Trust team domain & AUD tags

Database provider and version

Storage configuration (R2)

Secrets & webhook configuration

When an operator clicks "Provision", the Lucca engine reads these values and calls the appropriate APIs — GitHub, Cloudflare, Neon — to create the full environment. Every value is auditable, every change is tracked.

Environments

Multi-Environment Architecture

Every project operates across two deployment environments, both managed and monitored through Mocca. Same codebase, separate infrastructure, independent lifecycles.

🟡 Test / Staging

Deploys on staging branch push
Uses test domains (e.g. crm-test.clientname.nz)
Connects to staging database
Protected by Zero Trust policies
Used for client review & QA

🟢 Production

Deploys on main branch merge
Uses production domains (e.g. crm.clientname.nz)
Connects to production database
Protected by Zero Trust policies
Atomic zero-downtime deploys

Both environments share the same codebase and CI/CD pipeline. Mocca tracks deployment status, commit hash, and last-deploy timestamp for each environment independently — giving operators real-time visibility across the entire fleet.

Enterprise Infrastructure. Startup Speed.

Every environment is provisioned in minutes, secured by default, and monitored continuously. The same architecture that protects financial institutions — available to every client, at every scale.

ian@mio.nz · mio.nz