ColivingLiguria

S.r.l. — Startup Innovativa
Apply Now

4 min read

SCALING_ARCHITECTURE.md - The Zero-Cost Enterprise Stack

The Vision: To build and maintain a highly scalable, dynamic, and media-rich web ecosystem for Coliving Liguria without incurring traditional server hosting costs or succumbing to repository bloat.

1. 🏛️ The Architecture Paradigm: JAMstack

The Coliving Liguria platform operates on the JAMstack (JavaScript, APIs, and Markup) architecture.

It is a common misconception that our Quartz-based website is purely “static”. While the HTML is pre-rendered for lightning-fast delivery, the platform is highly dynamic. We utilise a distributed microservices approach rather than a single, expensive, monolithic server.

The Core Infrastructure (€0/month)

  • Frontend Hosting (Cloudflare Pages): Serves the Quartz React site. It caches our site globally across edge nodes, meaning it can handle millions of hits per month for free.
  • The Database (Cloudflare D1): A serverless SQLite database. It powers the Candidate Register, the future People Register, and the Financial Register.
  • The API Layer (Cloudflare Functions): Acts as the secure backend, reading/writing to D1 and managing user authentication (Zero Trust/Magic Links) without needing a running Node.js server.

2. 🗄️ Media & Asset Decoupling (Solving Git Bloat)

The most critical rule for scaling this architecture is: Never store heavy media inside the Git repository. GitHub has a strict 100MB file limit and a ~1GB repository limit. Overloading the repo will break local development and crash Cloudflare deployments.

To scale visually whilst paying nothing, we decouple our media:

A. Video Content (Tours, Interviews, Guides)

  • The Problem: Videos consume massive bandwidth and repository space.
  • The Solution: YouTube (Unlisted).
  • The Workflow: Upload all high-quality property tours to a Coliving Liguria YouTube channel. Set visibility to “Unlisted” so they do not appear in public search results. Embed the provided <iframe> directly into the Quartz Markdown pages. Google handles the heavy streaming bandwidth for €0.

B. High-Resolution Images (Thousands of Photos)

  • The Problem: Raw .heic, .png, or .jpg files add up rapidly, bloating the repository.
  • The Solution 1 (Lightweight): Convert all UI and core property images to the .webp format before adding them to Quartz. This reduces file size by up to 80% with no visible quality loss.
  • The Solution 2 (Enterprise Scale - Cloudflare R2): If the image library exceeds 1GB, we migrate to Cloudflare R2 (Object Storage). The free tier provides 10GB of storage per month. Images are uploaded to R2, and we simply paste the R2 URL into our markdown files.

C. Heavy PDF Documents (Architectural Plans, Massive Manuals)

  • The Problem: PDFs larger than 25MB slow down the Git checkout process.
  • The Solution: Google Drive Integration. The repository already utilises a symlink for Google Drive. Host heavy, static PDFs in the shared Coliving Liguria Google Drive and provide a standard download link button on the Quartz website.

3. ⚙️ The Microservice Bridge: Heavy Computing

Cloudflare’s serverless environment is phenomenal for routing and databases, but it cannot run heavy native binaries like the pdflatex compiler.

The Dedicated Document Engine

To generate complex legal contracts automatically, we isolate the heavy lifting:

  • The Setup: A lightweight Virtual Private Server (VPS) running Ubuntu, Python (FastAPI), and TeX Live.
  • The Bridge: We install a Cloudflare Tunnel (cloudflared) on the VPS.
  • The Workflow: When a user clicks “Generate Contract” on the Cloudflare site, a secure API request is routed through the tunnel to the VPS. The VPS compiles the PDF and returns it to the user.
  • Cost: This is the only component that requires a nominal fee (approx. €5/month for a basic Hetzner or DigitalOcean droplet). It keeps the heavy computing entirely separate from the web traffic.

4. 📈 Scaling Limits & Future-Proofing

This architecture is designed to scale to tens of thousands of users without modification.

When would we actually need to upgrade?

  1. D1 Database Reads/Writes: The free tier allows 5 million reads and 100,000 writes per day. We will only need to pay if we exceed this massive daily limit.
  2. Cloudflare Workers AI: The free tier allows 10,000 AI Chatbot queries per day.
  3. VPS Overload: If 500 people try to generate a LaTeX PDF at the exact same second, the €5 VPS will crash. At that point, we simply upgrade the VPS RAM (to €10/month) or implement a queueing system.

Conclusion: By ruthlessly separating static code (GitHub), heavy media (YouTube/R2), and heavy computing (VPS), Coliving Liguria achieves maximum performance and scalability with near-zero overhead.

Graph View