ColivingLiguria

S.r.l. — Startup Innovativa
Apply Now

6 min read

FUTUREPEOPLEREGISTER.md - The Master Architecture

The Vision: To build a fully automated, self-serve Enterprise Resource Planning (ERP) and Contract Lifecycle Management (CLM) portal for Coliving Liguria. This system unifies the Candidate, Bureau, Resident, and Financial Registers into a single, seamless user journey, eliminating manual data entry and administrative bottlenecks.

1. 🎯 The Ultimate Goals

The primary objective of the PeopleRegister is to achieve “Zero-Touch Administration” for the standard lifecycle of anyone interacting with the Coliving Liguria Living branch (Volunteers, Digital Nomads, Residents).

Specifically, the goals are:

  1. Total Data Unification: Eliminate data silos. A person’s data is entered once by them and cascades through their application, their legal contract, their residency status, and their financial ledger.
  2. Self-Serve Legal Pipeline: Empower users to generate, read, and sign their own contracts securely via a private web portal, without requiring an administrator to manually compile LaTeX files.
  3. Financial Transparency: Provide every user with a live, personal financial dashboard reflecting their exact standing with the company, deeply integrated with the rules of Attachment F (Gestione Finanziaria).
  4. AI-Driven Legal Support: Reduce the burden of answering repetitive contractual questions by deploying a custom AI Chatbot trained exclusively on Coliving Liguria’s legal documents, with a seamless human fallback.

2. 🧬 The Unified Trinity: Candidate + Bureau + Resident

The PeopleRegister replaces the concept of three separate databases. Instead, a person exists as a single entity moving through different “States” within one unified SQL database (Cloudflare D1).

Phase 1: The Candidate State (Public Intake)

  • The Interface: The public /apply page on the Quartz site.
  • The Data: Low-friction data collection (Name, Email, Dates, Volunteer/Pro status, Skills).
  • The Action: The user submits the form. They are logged in the database with the status applied. No sensitive legal data is asked for yet, maximizing conversion and respecting GDPR.
  • The Trigger: An admin reviews the application and changes the status to approved_for_onboarding.
  • The Interface: The system automatically emails the user a secure, one-time “Magic Link” (powered by Cloudflare Zero Trust). This grants them passwordless access to their Private Dashboard.
  • The Data: The user is now prompted to complete their “Legal Profile”. They input highly sensitive data required by the Bureau Register: Passport/ID numbers, Codice Fiscale, permanent address, and emergency medical information.

Phase 3: The Bureau State (Automated Contract Generation)

  • The Trigger: Once the Legal Profile is complete, the user clicks “Generate Contract”.
  • The Action: The frontend sends a secure API request to the backend LaTeX engine. The engine injects their exact data into the _RRInjData.tex format, compiles the specific contract (e.g., Contract_Residents or PR_AddPre_R), and returns the final PDF.
  • The Signature: The user downloads the PDF, prints the Hybrid Signature Sheet (complete with the cryptographic SHA-256 hash), signs it, and uploads a photo of the signed sheet back to the portal.

Phase 4: The Resident State (The Final Integration)

  • The Trigger: You (the admin) verify the uploaded signature and countersign.
  • The Action: The user’s status changes to contract_signed. They are officially moved to the “Resident” state. Their dates are locked into the property calendar, their room code (from All. R) is assigned, and their Financial Ledger is activated.

3. 💰 The Financial Dashboard (Attachment F Integration)

Because the Coliving Liguria Living branch handles payments, deposits, and potentially debt lines, the Private Dashboard must serve as a window into the FinancialRegister.

When a user logs into their portal, they will see a dedicated “Financials” tab. This tab is governed by the rules explicitly laid out in Attachment F (Gestione Finanziaria).

Features of the Financial Dashboard:

  • Live Balance (Il Saldo): A clear display of their current credit or debit balance with the company.
  • Pending Payments: A timeline showing upcoming due dates for rent or flat-rate utility contributions (Quote Fisse), calculated automatically based on their contract type (Weekly vs. Monthly frequency).
  • Security Deposit Status (Deposito Cauzionale): Clear visibility of the deposit held, and the automated timeline for its return post-departure, as mandated by Attachment F.
  • Automated Invoicing/Receipts: Users can download digital receipts for payments made directly from this portal.

4. 🤖 The Legal AI Chatbot (RAG System)

To handle the immense volume of questions generated by complex legal documents, the Private Dashboard will feature an AI assistant.

  • How it Works (RAG - Retrieval-Augmented Generation): The AI is strictly tethered to your compiled LaTeX contracts. When a user asks, “When do I get my deposit back?”, the system searches the text of their specific contract and Attachment F, feeds that text to the AI, and formulates an answer based only on your legal framework.
  • The Human Fallback: The AI will inevitably encounter edge cases or complex nuances. Every chat interface will feature a prominent button: “I need human clarification”. Clicking this will automatically package the user’s question, the AI’s attempted answer, and their contract details, sending it as a high-priority ticket to legalinfo@colivingliguria.com.

5. 🛠️ The Technical Blueprint: Tools & Infrastructure

To build this securely, cheaply, and robustly, we will utilize a hybrid architecture. The heavy lifting is done by Cloudflare’s free tier, while the specific LaTeX compilation is handled by a lightweight, dedicated server.

A. The Frontend & Authentication (Cloudflare - €0/month)

  • Hosting: Cloudflare Pages (serving the Quartz/React site).
  • Authentication: Cloudflare Zero Trust (Access). This handles the secure “Magic Links” and OTPs (One-Time Passwords) so users can access their Private Dashboard without you needing to build complex password reset flows.

B. The Unified Database (Cloudflare D1 - €0/month)

  • Technology: Cloudflare D1 (Serverless SQLite).
  • Structure: We will expand the current candidates schema to become a massive people table, linking out to financial_ledgers, contract_history, and legal_profiles.

C. The API & AI Brain (Cloudflare Workers - €0 to €5/month)

  • Routing: Cloudflare Workers will handle all form submissions, database queries, and data validation securely at the edge.
  • The Chatbot: We will use Cloudflare Workers AI (to run the language model) and Cloudflare Vectorize (to store the searchable text of your contracts). This keeps the AI ecosystem entirely within your current infrastructure.

D. The Document Engine (The VPS - ~€5 to €10/month)

  • The Problem: Cloudflare cannot run pdflatex to compile your contracts.
  • The Solution: We rent a cheap, reliable Virtual Private Server (VPS) from Hetzner, DigitalOcean, or Linode running Linux (Ubuntu).
  • The Setup: We install Python, FastAPI (main.py), and a full TeX Live distribution on this server.
  • The Bridge: We use a Cloudflare Tunnel to securely connect this external VPS to your Cloudflare ecosystem. When Cloudflare Workers need a PDF, they send the JSON data through the secure tunnel to the VPS, the VPS compiles the LaTeX, and sends the PDF back to the user’s browser.

Phase 1 Execution Plan

  1. Schema Redesign: Map all _RRInjData.tex variables to new columns in the Cloudflare D1 database.
  2. Private Routing: Set up Cloudflare Zero Trust to protect the /private route on the Quartz site.
  3. React Dashboard: Build the UI components for the Legal Profile completion and the Financial Ledger display.

Graph View