Tech Context

1. Platform & Configurations

• OS: Zoho Creator (SaaS)
• Language: Deluge Scripting
• Database: Zoho Internal DB (Relational)

Environment Settings

• Fiscal Year Start: October 1st.
• Date Format: dd-MMM-yyyy (e.g., 21-Jan-2026).
• Time Zone: Europe/Rome (CET/CEST).
• Time Format: 24-hr.
• Data Import: CSV imports used for Invoices (from accounting systems of different countries).
• Integrations: External APIs (ECB for currency conversion).

2. Developer Workflow

Administrative procedures for environment sync.

Export Procedure

To obtain the latest Zoho Creator application export:

1. Log in to Zoho Creator IDE.
2. Open the application in the IDE.
3. Click the Export button to download the .ds file.
4. Save/overwrite the file in the zoho_exports/ directory as budget_contracts.ds.
5. GIT will handle versioning of changes.

Import Procedure

1. Log in to Zoho Creator.
2. Navigate to the Applications section.
3. Click "Import Application".
4. Upload the budget_contracts.ds file from zoho_exports/.
5. Follow the on-screen prompts (select options for data, users, etc. as needed).
6. Verify the imported application and test functionality.

[!TIP] Procedural guardrails and technical patterns are delegated to the Zoho Architect Skill.

3. Automated Testing Framework

To ensure logical correctness of Deluge scripts without slow UI cycles.

Components

• Test Specification: docs/tests.md (Gherkin format).
• Extraction Script: tests/extract_tests.py - Converts tests.md into .feature files.
• Logic Engine: zoho_simulation script (../.agent/skills/zoho_simulation/scripts/logic_engine.py) - Python implementation of the Deluge algorithms (FY Allocation, Budget Recalculations).
• Test Runner: behave - Executes scenarios via step definitions.

Setup and Execution

1. Environment: Python 3.x virtual environment in .venv.
2. Installation: pip install behave.
3. Execution:

   source .venv/bin/activate
   python3 tests/extract_tests.py
   behave tests/features

[!TIP] For detailed simulation logic and FIFO erosion scenarios, see the Zoho Simulation Skill.

4. Entity Relationship Model (ERM)

Dettaglio dei Legami

Legame	Tipo	Descrizione
Bucket -> Versioni	Lookup	Collega ogni snapshot (Rolling Forecast) al suo Bucket. La chiave logica è Bucket + FY + Expense_Type.
Bucket -> Contratti	Lookup	Il legame fondamentale. Ogni contratto (Proposed o Approved) eredita lo stream e deve matchare il Tipo della versione.
Fiscal Year -> Versioni	Lookup	Definisce a quale anno fiscale appartiene la versione.
Contratti -> Subforms	Subform	Un contratto multi-anno "esplode" in righe di Contract_FY_Allocation, ognuna collegata a un Fiscal_Year.
Invoices -> Subforms	Subform	Permette di allocare il costo reale di una fattura su uno o più anni fiscali (Invoice_FY_Allocation) per competenza.
Fiscal Year -> Allocations	Lookup	(Condiviso) Permette di filtrare sia l' Impegnato che lo Speso per anno fiscale nelle versioni di budget.
Contratti -> Invoices	Lookup	Collega le fatture reali all'impegno contrattuale. Il matching avviene tramite imported_id (Job/Contract Code).

Flusso di Propagazione

1. Contratto: Quando viene salvato, crea/aggiorna le righe in Contract_FY_Allocation.
2. Fattura: Quando viene salvata/riconciliata, crea/aggiorna le righe in Invoice_FY_Allocation basandosi sulla competenza.
3. Bucket: Funge da "ponte" per trovare tutte le allocazioni (impegnate e spese) che devono concorrere al budget.
4. Versione: Il workflow Update_Budget_Totals cerca tutti i contratti e le fatture del Bucket, segue il legame con le rispettive Allocazioni (Contract_FY_Allocation, Invoice_FY_Allocation) filtrando per il Fiscal_Year della versione, e aggiorna i totali (Impegnato, Totale Contratti, Speso).