ColivingLiguria

S.r.l. — Startup Innovativa
Apply Now

11 min read

TODOAI: MASTER ARCHITECTURE PLAN - BureauRegister, Bilingual Automation & Sync Dashboard

0. Executive Summary & Objective

This master plan outlines the complete overhaul of the ColivingLiguria document management system. The goal is to establish a rigorous, automated, and natively bilingual document generation pipeline. The core of this architecture is the creation of a new system register: the BureauRegister (CL-BR). This register will house an SQL database acting as the absolute Single Source of Truth (SSOT) for all document versions, metadata, and legal flags. Python automation will bridge this database with the LaTeX compilation engine and the Sync Dashboard, allowing seamless generation, updating, and downloading of multi-language PDFs directly to the user’s desktop.

PHASE 1: “BureauRegister” (CL-BR) Creation & SQL Database

The system must no longer rely on hardcoded LaTeX files or manual updates inside Attachment R for version tracking.

  1. Register Architecture: Create a new register directory named BureauRegister (CLI command prefix: CL-BR). Like other registers, it must contain a frontend and a backend directory, and securely connect to Cloudflare.

  2. SQL Database (The SSOT): Initialize a new SQL database within CL-BR. This database is the only place where document metadata and versions are manually updated or stored.

  3. Database Schema (DocumentRegistry): Create the main table with the following strictly typed columns to handle the complex versioning and vexatious logic inherited from Allegato R:

    • Identification & Categorization:

      • Doc_ID (String / VARCHAR, Primary Key): Unique identifier (e.g., ‘Contract_Internship’, ‘Attachment_G’).
      • Doc_Category (String / ENUM): The system must autonomously analyze the historical LaTeX repository and define a maximum of 5 to 10 standardized categories (e.g., Contract, Attachment, Report, Tool, Project, Policy).
      • Prefix_Letter (String / CHAR): The leading identification letter (e.g., ‘R’, ‘G’, ‘F’). Note: The same letter means different things depending on the Doc_Category (e.g., ‘R’ in Contract means “Residential”, but ‘R’ in Attachment means “Registro Interno”).

    • Versioning (Following Allegato R logic):

      • Major_Version (Integer): The primary structural version (e.g., 1 for ‘R1’, 2 for ‘R2’).
      • Minor_Version (Integer): The specific instance/revision version (e.g., 1, 2, formatted as ‘-01’, ‘-02’).
      • Full_Version_Code (String / VARCHAR): Auto-generated internal bureaucracy code combining the above (e.g., R1-01).

    • Content & Localization:

      • Title_IT (String / VARCHAR): Official Italian Title.
      • Title_EN (String / VARCHAR): Official English Title.
      • File_Path (String / VARCHAR): Relative path to the .tex file in the repository.

    • Structural & Legal Data (Vexatious Logic):

      • Total_Articles (Integer): The total number of articles contained in the document.
      • Is_Vexatious (Boolean): True if the document contains any vexatious clauses requiring double signature.
      • Vexatious_Articles_List (JSON Array of Integers / ARRAY): A specific list of the article numbers that are vexatious (e.g., [1, 3, 4]).
      • Vexatious_Desc_IT (String / TEXT): Italian description of the vexatious clauses for the final contract summary block.
      • Vexatious_Desc_EN (String / TEXT): English description of the vexatious clauses.

PHASE 2: Python Automation & Data Injection (The “Sync Engine”)

The LaTeX macros and the internal registry documents must act strictly as dumb endpoints. They contain zero hardcoded data regarding versions, titles, or legal flags. Their sole purpose is to receive and format data injected from the CL-BR SQL database.

To achieve this, the Python automation must be structured into a highly robust, multi-step pipeline that acts as a pre-compilation hook.

  1. Database Extraction & Data Transformation (The Core Script):

    • The primary Python script within the CL-BR backend must securely connect to the SQL database.
    • Fetch Operation: Retrieve the complete, current dataset of all documents (Contracts, Attachments, Tools) including their Version Codes, Bilingual Titles, Vexatious Boolean flags, and Vexatious Descriptions.
    • Transformation Operation: The script must process these raw SQL rows and transform them into two distinct strings of raw LaTeX code:
      1. A formatted LaTeX table body (for the Internal Registry document).
      2. A block of expl3 (LaTeX3) property lists or variable definitions (for the Smart Closing Macro data dictionary).

  2. Targeted LaTeX Injection (Safe Overwrite Mechanism):

    • The Python script must never overwrite entire .tex files, as this would destroy the structural LaTeX code. Instead, it must use a Targeted Regex Injection mechanism.
    • Injection Zones: The target .tex files (both the Internal Registry document and the Smart Closing Macro file) must contain specific, hardcoded comment boundaries (e.g., % --- BEGIN AUTO-INJECTED BUREAU DATA --- and % --- END AUTO-INJECTED BUREAU DATA ---).
    • The script must locate the target files, find these exact boundaries, clear everything between them, and paste the newly transformed LaTeX code.

  3. Task A: Generating the Official Internal Registry:

    • The script targets the specific .tex file serving as the company’s Internal Registry (formerly known as Allegato R).
    • It injects the comprehensive list of all company documents, creating a master index table that displays the Document Category, Prefix Letter, Version Code, and Bilingual Titles. This ensures the printed registry perfectly mirrors the SQL database.

  4. Task B: Populating the Smart Closing Macro Dictionary:

    • The script targets the specific .tex file containing the \makeClosingBlock macro definitions.
    • It injects the underlying data dictionary. For example, it writes the LaTeX variables that map the key “G” to its current version “G1-01”, its title, and its vexatious properties. This arms the macro with the intelligence needed to execute Phase 3 dynamically.

  5. Sync Dashboard Integration (The Pre-Flight Hook):

    • The main sync-document dashboard architecture must be tightly coupled with this Python script.
    • Blocking Operation: Whenever a user clicks “Compile & Download” on the dashboard frontend, the system MUST execute the Python Sync Engine first.
    • The dashboard backend must wait for a successful exit code (HTTP 200 / Exit 0) from the Python script before triggering any pdflatex compilation commands.
    • If the Python injection fails (e.g., database unreachable, injection tags missing), the compilation must abort, and an error must be surfaced to the user UI, preventing the generation of outdated or legally invalid PDFs.

PHASE 3: The “Smart Closing Macro” Implementation & Python Injection

With the internal data dictionary now securely housed in the CL-BR SQL database, the LaTeX macro must handle the dynamic rendering of the contract’s final pages without any hardcoded version numbers.

  1. File Location & Architecture: - Create a dedicated system macro file: System/pre/pre/macros/contract_closing.tex.

    • The macro \makeClosingBlock{<Attachments_List>}{<Contract_Articles_List>} will act as the master compiler for the end of every contract.

  2. The Python Injection Mechanism (Crucial Step):

    • The macro itself is “dumb”. It relies on the Python script (sync_bureau.py) from Phase 2.
    • When triggered, the Python script reads the SQL database and automatically writes/overwrites a hidden LaTeX definitions file (e.g., injected_bureau_data.tex) using expl3 (LaTeX3) property lists or associative arrays.
    • This injected file contains the exact Version_Code, Bilingual_Title, Is_Vexatious boolean, and Vexatious_Desc_IT/EN for every existing attachment (A to Z), ensuring the macro always pulls the latest SQL data.

  3. Inputs:

    • #1 = Comma-separated list of active attachments for the specific contract (e.g., G, F, R, D).
    • #2 = Explicit list of vexatious main contract articles, manually provided per contract (e.g., Art. 1:{Prevalenza Documentale}, Art. 2:{Proprietà Intellettuale}). Note: The macro cannot guess contract articles, so they must be passed as an input.

  4. Execution Flow & Dynamic Rendering:

    • Step A (Summary Table): The macro iterates through input #1. It cross-references each letter with the injected expl3 data. It then generates a perfectly formatted LaTeX table printing the Attachment Letter, its auto-fetched Version_Code (e.g., “G1-01”), and its Bilingual Title.
    • Step B (Vexatious Clauses - Approvazione Specifica): - Prints the standard legal header: \section*{\Bilingual{Approvazione Specifica ai sensi degli art. 1341 e 1342 c.c.}{...}}.
      • Opens an itemize list.
      • Loop 1 (Manual Articles): Iterates through input #2 and prints the specific contract articles as bullet points.
      • Loop 2 (Smart Attachments): Iterates through input #1 again. It checks the injected SQL boolean flag Is_Vexatious. If True (e.g., Attachment G or F), it automatically generates a bullet point printing the Vexatious_Desc_IT/EN. If False (e.g., Attachment R), it skips it silently.
    • Step C (Signature Block): Automatically appends the \printConditionalSignatureBlock macro, utilizing the existing signatory variables to close the document.

PHASE 4: LaTeX Single-Source Bilingual Refactoring & Legal Guardrails

Eradicate the legacy system of maintaining separate .tex files for translations. We are moving to a strictly single-file architecture to guarantee perfect alignment between languages and eliminate maintenance overhead.

  1. Purge Legacy Files: Scan the repository and permanently delete all separate _EN.tex or translated files.

  2. \Bilingual Macro Best Practices:

    • Refactor ALL remaining .tex files (contracts, attachments, registers).
    • Every string of readable text must be wrapped in \Bilingual{Italian Text}{English Text}.
    • Strict Formatting Rule: The system will compile the Italian text in standard font, and the English text immediately following (or below) in italics to create clear visual separation.
    • Anti-Crash Rule: Instruct the compiler/AI to break down long paragraphs into smaller, sentence-by-sentence \Bilingual blocks. Do NOT wrap entire pages of text in a single macro, as this makes debugging LaTeX compilation errors impossible.

  3. Conditional Compilation Flag: - Modify the core \Bilingual definition in the pre.tex files to listen to a build flag passed by the Sync Dashboard.

    • It must support three output modes: IT (Italian only), EN (English only), or BOTH (Bilingual).

  4. CRITICAL LEGAL GUARDRAILS (Savona Jurisdiction & Courtesy Translation):

    • The Legal Reality: The exclusive competent court is Savona, Italy. Italian courts only work in Italian. If a purely English contract is brought to court, it requires a highly expensive sworn translation (traduzione asseverata). A bilingual document with a prevalence clause saves these costs entirely.
    • Prevalence Clause: Every bilingual contract must include a clause stating: “In caso di discrepanze o dubbi interpretativi, fa fede esclusivamente la versione in lingua italiana.”
    • The “Facsimile” Rule for EN Mode: The English translation is strictly an unofficial “courtesy translation” (often AI-assisted) and holds ZERO legal efficacy.
    • Automated Disclaimer Injection: Search the macros directory for the \translationFooter command. The system MUST automatically inject this disclaimer at the bottom of the page whenever the document is compiled in EN or BOTH mode.
    • Signature Block Protection: If compiled in EN (English Only) mode, the system must alter or watermark the signature block to prevent the user from legally binding themselves to the English text alone. It must explicitly state: “This is an unofficial facsimile. Signatures must be affixed to the official Italian or Bilingual document.”

PHASE 5: Sync Dashboard Frontend & Compilation Engine

Build a highly articulated and advanced user interface within the sync-document dashboard to interact with the BureauRegister and the LaTeX compiler. The UI must flawlessly respect the established ColivingLiguria frontend styling parameters.

  1. Advanced Document Navigation UI (Mirroring LaTeX Directories):

    • The frontend must not just list files, but visually reconstruct the exact folder and sub-folder hierarchy as it exists in the physical LaTeX repository.
    • The UI will render an interactive, collapsible “File Tree” component, allowing the user to navigate through the exact directory paths to find every single .tex file.
    • The tree structure must be dynamically generated by querying the BureauRegister SQL database (mapping File_Path to visual folders).
    • CRITICAL LEGAL EXCLUSION: The system must strictly ignore, hide, and exclude any files or directories located within the Private_Archive path.

  2. Strict UI/UX Styling & Palette Compliance:

    • The entire dashboard section must be designed in perfect harmony with the existing ColivingLiguria design system.
    • Colour Palette: Strictly utilize the official primary, secondary, and accent colours for the folder icons, selection states, and action buttons.
    • Typography & Components: Use the established frontend component library (e.g., standard dropdowns, checkboxes, and typography) to ensure a seamless and professional user experience across the dashboard.

  3. User Interaction & Granular Control:

    • Single & Batch Selection: Implement checkboxes next to every folder (to select all contents) and every individual document for precise multiple selection.
    • Language Selector: Include a prominent control (dropdown or toggle) with three compilation options: Italian, English, and Bilingual.
    • Action Buttons: Add a primary "Compile & Download to Desktop" button for batch operations, and a smaller, quick-action download icon next to each individual file in the tree.

  4. Backend Compilation Trigger & Delivery:

    • When a download is triggered, the backend loops through the selected document paths.
    • For each document, it dynamically injects the selected language flag into the pdflatex compilation command.
    • The backend compiles the PDFs and triggers an automatic download directly to the user’s local OS Desktop. If multiple files or entire folders are selected, the system must automatically package them into a .zip archive preserving the folder structure.

    Quando implementi uttal la aprte biligue devi andare a spigaer esttmatne comeufunzoan i un docuemtnio markdon dentor allennote della cartella latex in mnaiera che qualcuno che vien dopo sappai cpaire perfettament conme funzoian quest fiunzione di andare arendere tutot nilingue.

    Quando si trata di adnre a fer la parte di scaricare un file devo poter scelgeire tra 4 opzini inglese o italiano e poi devo poter dire se lo voglio con o senza allegati, se con gli allegati allora me lo deve scaricare lunghissimo con tutti gli allegati in input, se invece metto senza alleagti mi deve geneare soltanto il contratto in PDF chge ha la tabella e tutto con gli allegati ma senza aver etutte le tantissime pagien deglialleagti, asicuarit che questoanceh sia implemeantatio.

Graph View