ColivingLiguria

Apply Now

4 min read

🧪 Anime.js Laboratory

Demonstrating dynamic component capabilities.

Experiment 1: Physics & Loop

Experiment 2: Staggered Grid

Experiment 3: Typography

Coliving Liguria

System Architecture & Deployment Guide

This document is the Master Reference for understanding how the ColivingLiguria (CL) digital ecosystem is built, structured, and deployed.

1. Project Architecture (The Monorepo)

The project is organized as a Federated Monorepo located at ~/Projects/CL.

Core Directories

  • CL_Admin/: The command center. Contains monitoring scripts, database schemas, and the critical scripts/ folder for synchronization.
  • Quartz_CL/: The Frontend. A customized Quartz (Static Site Generator) instance that renders the public website.
  • LaTeX_CL/: The Bureaucracy. Contains official legal contracts and detailed house registries (e.g., RE-IN-001). This is often treated as a submodule or separate entity during deployment to keep the build light.

Data Flow

  1. Input: User edits Markdown in Quartz_CL/content or LaTeX in LaTeX_CL.
  2. Sync: CL-sync script orchestrates the update (see below).
  3. Build: Cloudflare Pages builds Quartz_CL into a static site.
  4. Output: Live website at colivingliguria.pages.dev.

2. Site Structure (Quartz_CL)

The frontend is built on Quartz 4, highly customized with React/Preact components.

Layout

  • content/: All markdown files (.md). This aligns 1:1 with the URL structure.
    • System/: Meta-documentation (like this guide).
    • Diary/: Daily logs.
    • Contracts/: Public versions of LaTeX documents.
    • Rule: Every folder MUST have an index.md file.
      • Why? It acts as the “cover page” for that folder in the navigation.
      • Naming: Do NOT use Folder/Folder.md. Always rename it to Folder/index.md.
      • Exceptions: Internal System/ folders do not strictly require this, but it is good practice.
      • CRITICAL (TSX Mapping): If you rename Folder/Folder.md to Folder/index.md, the slug changes from parent/folder/folder to parent/folder. You MUST update quartz.layout.tsx to match the new slug, otherwise the custom TSX component will likely disconnect!
  • quartz/: Source code of the generator.
    • components/: CRITICAL. These are the TSX components used to build pages.
      • pages/: Full page templates (e.g., Content.tsx).
      • Head.tsx, Footer.tsx: Global layout elements.
      • Custom Components: Specific features like FinancialAdvisory.tsx or WoodStove.tsx.
    • plugins/: Custom transformers and emitters for the build pipeline.
  • quartz.layout.tsx: Defines which components appear on which page types (Home vs Detail vs Tags).
  • quartz.config.ts: Global configuration (Plugins, Colors, Fonts).

Key Packages

We use standard npm packages managed via package.json. Notable additions:

  • anime.js: A lightweight JavaScript animation library.
    • Usage: Used for complex UI animations (e.g., entrance effects, diagram flows) that CSS cannot handle.
    • Integration: Imported in TSX components (import anime from 'animejs') and triggered inside useEffect hooks.

3. The Deployment Workflow (CL-sync)

We do NOT use standard git push for the main site. We use a custom script: CL-sync.

Why?

  1. Complexity: We have multiple interlinked repos (DB, LaTeX, Site).
  2. Safety: We need to back up databases before deployment.
  3. Performance: LaTeX_CL is heavy. We exclude it from the Cloudflare build to avoid timeouts.

The CL-sync Pipeline

The script (CL_Admin/scripts/CL-sync) performs these steps in order:

  1. Database Sync: Runs CL-sync-db to backup local D1 databases.
  2. LaTeX Sync: Runs CL-sync-latex to compile critical documents.
  3. Google Drive: Checks sync status (informational).
  4. Main Repo Sync: Commits and Pushes changes to the main branch (Development history).
  5. Bridge to Production:
    • Checks out a special orphan branch: deploy-quartz.
    • Merges main into it.
    • removes the LaTeX_CL submodule/folder (to keep the payload small for Cloudflare).
    • Pushes deploy-quartz to GitHub.
  6. Monitoring (New):
    • The script polls Cloudflare API (via wrangler) to check the build status.
    • It waits until the deployment is SUCCESS or FAILURE.
    • If Success: Reports the live URL.
    • If Failure: Reports the error and a direct link to the logs.
  7. Restore: Switches back to main and restores LaTeX_CL so you can continue working.

How to Deploy

Simply run from any terminal:

CL-sync

Never manually push to deploy-quartz unless you are debugging the pipeline itself.

4. Troubleshooting

  • “Timeout waiting for deployment”: The build took longer than 5 minutes. Check Cloudflare Dashboard.
  • “Merge conflict in deploy-quartz”: Usually happens if LaTeX_CL was modified oddly. The script tries to auto-resolve by removing LaTeX_CL, but if it fails, delete the deploy-quartz branch locally and let the script recreate it: git branch -D deploy-quartz.

Graph View

Backlinks