Skip to content

alaivOS Business — Platform Master Reference

Version: 2.1 · Date: March 2026 · Owner: Citerius Holdings LLC
Audience: All agents, engineers, PM
Status: Canonical — supersedes all prior architecture documents

This is the authoritative source of truth for the alaivOS Business platform. Every agent operating in this project reads this document first. Anything not in a canonical KB document does not exist as a locked decision.


§01 — Product Portfolio

Three Products, One IP Owner

Citerius Holdings LLC owns three products. Their relationships are precise and non-negotiable.

alaivOS Personal alaivOS Business Tractus
Type Consumer Life OS SME Back-Office OS Logistics Branch of Business
Deployment Separate product entirely Mode A: per-client VPS Mode B: multi-tenant SaaS
Stack Flutter + SQLite + Supabase Odoo + n8n + Google ADK + Nextcloud Firebase + Cloud Functions + Flutter
AI layer On-device (TFLite, privacy-first) Cloud Personas (Google ADK + Gemini) Cloud Personas (Cloud Functions)
Data layer SQLite sovereign "odoo" (default) "firestore_primary"
Revenue B2C subscription B2B SaaS subscription Trust Fee + subscriptions
IP owner Citerius Holdings LLC Citerius Holdings LLC Citerius Holdings LLC
Convergence None — permanently separate Parent backbone Logistics Branch of Business

Personal ↔ Business convergence: permanently none. They share Flutter shell, glassmorphism design system, and privacy philosophy. They share no backend infrastructure, no auth system, no database, no agent runtime. This project covers alaivOS Business only. alaivOS Personal canonical documents are irrelevant here.

Branch Taxonomy (March 2026)

Branch Brand Deployment Mode Status
Logistics Tractus B Architecture complete, GTM ready
Construction Construx B Architecture complete, capsule specs in progress
Generic SME (alaivOS Business) A Blueprint complete
Retail TBD A Planned
Legal Firm TBD A Planned
Healthcare Admin TBD A or B Planned

§02 — Deployment Models

Every branch declares exactly one deployment mode. This is the most fundamental architectural decision — it determines hosting, tenancy, data layer, legal obligations, and agent runtime.

Deployment Mode A — Private Instance

Citerius provisions a dedicated infrastructure instance per client. The client's data is fully isolated. No external parties transact — it is a private back-office tool for one SME.

  • Stack: Odoo (Community) + n8n + Google ADK + Nextcloud
  • Hosting: Hetzner VPS per client
  • Tenancy: Single-tenant
  • Data layer: "odoo" (default) or "odoo+firestore" (hybrid)
  • Agent runtime: Google ADK + Gemini + n8n workflows
  • Citerius legal role: Infrastructure provider. SLA is a hosting agreement. Client data is client property.

Deployment Mode B — Platform SaaS

Citerius owns and operates the platform. Multiple external parties are tenants who transact on a shared platform. Citerius is the marketplace operator.

  • Stack: Firebase Auth + Firestore + Cloud Functions (Node.js 20) + Firebase Storage + Flutter
  • Tenancy: Multi-tenant — Citerius owns infra; external parties are platform tenants
  • Data layer: "firestore_primary" — always. Odoo is financial reporting satellite only.
  • Agent runtime: Firebase Cloud Functions, event-driven (Firestore writes + HTTP)
  • Citerius legal role: Marketplace operator. AML policy holder. Escrow liability. Platform ToS governs all tenant conduct.

Manifest Validation Rules (enforced at provisioning)

// deployment_mode "B" requires: data_layer "firestore_primary" + tenancy "multi-tenant"
// deployment_mode "A" requires: tenancy "per-client"
// data_layer "odoo+firestore" is valid with deployment_mode "A" only

§03 — Data Layer

Three Options

data_layer Mode Odoo role Firestore role
"odoo" A only Primary SoT for all data Not used
"odoo+firestore" A only Primary SoT for business records Secondary — multi-party sub-records, append-only
"firestore_primary" B only Financial reporting satellite — settlement events only Primary SoT for all operational data

Firestore → Odoo Sync Contract (Locked)

Model: Hybrid. Real-time for financial settlement. Nightly batch for analytics. This is locked.

Real-time trigger events (Finance Agent executes Odoo XML-RPC in same Cloud Function execution): - Financial settlement → Create Vendor Bill + Customer Invoice (< 60s) - Trust Fee deduction → Add line to client invoice (< 60s) - Insurance referral earned → Create referral revenue journal entry (< 60s) - Subscription payment → Create subscription invoice + mark paid (< 60s) - KYC status → VERIFIED → Update res.partner: kyc_verified=True (< 60s)

Nightly batch (02:00 UTC, complete by 04:00 UTC): - Trust Score recalculation → Update res.partner.trust_score - Shipment/project analytics → Route performance, on-time rate, incident count - KPI aggregates → MRR dashboard, entity count, volume metrics - Compliance expiry check → Update fleet.vehicle / project.task permit/insurance expiry flags

On Odoo failure: 3× retry with 2s/4s backoff → write reconciliation_tasks/{id} with full XML-RPC replay payload + notifyOps(). Firestore write is NEVER rolled back. Firestore is the legal source of truth. Reconciliation task enables mechanical replay.

Firestore Data Principles (Mode B — Non-Negotiable)

These rules apply to every Firestore collection in every Mode B branch. Capsule developers must comply or their capsule will be rejected at review.

  1. Append-only for all audit collections (handoffs, incidents, audit_log, escrow_events, kyc_verifications, phase_submissions) — no update or delete, enforced by Firestore security rules.
  2. Server timestamps onlycreatedAt must equal request.time. Client-supplied timestamps are informational only.
  3. No cross-tenant reads — A party can only read documents they are named in.
  4. Agent writes only through Cloud Functions — No Flutter client may write directly to audit collections.
  5. Hardware-signed offline events — Events written to the offline SQLite queue must be HMAC-SHA256 signed with the device hardware key at capture time. Unsigned events are rejected by the sync engine.

§04 — Persona Architecture

A Persona is a named, role-scoped AI agent with a defined RAG corpus, confidence thresholds, approval gate language, and Firestore collection access map. Branches apply Persona skins — configuration layers that give backbone Personas domain-specific identity and vocabulary without changing the underlying agent architecture.

Seven Backbone Personas

Persona ID Default Name Role Primary Trigger
sales-agent The Business Developer Lead nurturing, quote generation, pipeline management CRM event / scheduled
ops-agent The Operations Manager Workflow orchestration, task routing, approval gate management n8n workflow trigger
finance-agent The CFO Assistant Invoice review, cash flow alerts, payment reconciliation Accounting event
compliance-agent The Compliance Officer Regulatory monitoring, document expiry, audit trail management Scheduled + document event
hr-agent The People Manager Contractor onboarding, payroll prompts, workforce tracking HR event / scheduled
risk-agent The Risk Analyst Evidence evaluation, anomaly detection, incident classification Field event / media upload
analyst-agent The Business Analyst KPI synthesis, dashboard narrative, report generation Scheduled / on-demand

Skin Configuration Format

{
  "persona_id": "risk-agent",
  "skin": {
    "display_name": "The Load Guard",
    "domain_prompt": "You are operating in MX-US cross-border logistics...",
    "rag_corpus": ["sat_catalog_codes_v2024.json", "sct_permit_categories.json"],
    "confidence_thresholds": {
      "auto_block": 87,
      "human_review": 70,
      "auto_approve": 92
    }
  }
}

§05 — Capsule Marketplace

Capsules are installable capability modules that extend a branch. A capsule adds Personas, UI surfaces, Cloud Functions, Firestore collections, or Odoo module configurations — or any combination. Capsules are branch-agnostic by design: sector-specific vocabulary lives in the branch config, not in the capsule manifest.

Economics

Revenue split Condition
80% developer / 20% Citerius Standard
90% developer / 10% Citerius First 50 developers enrolled, for 12 months from their enrollment date

Capsule Manifest — Required Fields

{
  "capsule_id": "evidence-audit",
  "display_name": "Evidence Audit Trail",
  "version": "1.0.0",
  "data_interactions": {
    "firestore_reads": ["..."],
    "firestore_writes": ["..."],   // append-only collections only
    "odoo_reads": ["..."],
    "odoo_writes": [],             // writes to Odoo via sync contract only
    "external_apis": ["..."]
  },
  "deployment_mode_compatibility": ["B"],   // "A" | "B" | ["A","B"]
  "requires_append_only_write": true        // triggers extra security review
}

See BIZ-CAPSULE-REGISTRY.md for the full capsule taxonomy and per-capsule specs.


§06 — Monetization

alaivOS Business — Subscription Tiers (Mode A)

Tier Price Target
Starter $299/month 1–5 employees, basic back-office automation
Growth $699/month 5–20 employees, full Persona suite, capsule marketplace
Scale $1,499/month 20–50 employees, multi-branch, priority support
Custom Negotiated 50+ employees, dedicated VPS tier, SLA guarantees

Tractus (Mode B) — Revenue Streams

Stream Rate Notes
Starter Free 1 active shipment, no marketplace access
Basic $49/month Marketplace listing, compliance tracking
Pro $149/month Priority listing, capacity-matcher, analytics
Enterprise $499/month API access, custom workflows, SLA
Trust Fee 2–3% per shipment Escrow + insurance + audit trail — per transaction
Insurance referral 10–15% of premium Via Genda/Mutuus white-label (CNSF-licensed)
Carta Porte add-on $1.50–3.00/CFDI Bundled in Pro tier

Tractus Revenue Projections

Milestone MRR ARR Run Rate Assumptions
Beta Month 6 $9K $108K Early adopter pricing, limited marketplace
Month 12 $85K $1.02M Marketplace live, Trust Fee volume
Year 3 $1.8M+ Business OS + Tractus combined (base case)

§07 — Corporate Structure

Entity Type Jurisdiction Role
Citerius Holdings LLC LLC Wyoming, USA Parent entity. IP owner for all products. Stripe Connect. Investor-facing.
alaivOS (DBA) DBA of Citerius Wyoming Consumer platform brand.
Tractus (DBA) DBA of Citerius Wyoming Logistics marketplace brand.
A³ Synergy Group Operating entity Wyoming Business advisory. Tractus commercial partnerships.
TBD SA de CV SA de CV Jalisco, Mexico MX operations: Conekta, Carta Porte, insurance, customs brokerage. Week 1 Phase 1 hard blocker.

SA de CV is a hard blocker. All MX-side contracts (Conekta escrow, PAC agreements, CNSF insurance referral) require the SA de CV as the contracting entity. No MX contract can be signed without it.


§08 — All Locked Decisions

Every decision in this table is final. None are open for re-debate.

Decision Answer
Personal ↔ Business convergence None. Separate product, separate codebase, separate subscription. No planned convergence. Ever.
Tractus classification Logistics Branch of alaivOS Business. Not a capsule. Not a standalone product. Architecturally sovereign in data layer; shares platform model commercially.
Deployment mode field name "deployment_mode": "A" \| "B" in all manifests.
Tractus deployment mode Deployment Mode B — multi-tenant SaaS. Citerius is marketplace operator.
Construx deployment mode Deployment Mode B — locked. GC, subcontractor, inspector, and municipality all have simultaneous legal claims on the same site event. Firestore is the append-only operational ledger.
Tractus data layer "firestore_primary". Odoo is financial reporting satellite only, populated at settlement.
Construx data layer "firestore_primary". Same rationale as Tractus.
Firestore → Odoo sync model Hybrid: Finance Agent executes Odoo XML-RPC in same Cloud Function execution context. 3× retry with 2s/4s backoff. Failure creates reconciliation_tasks. Nightly batch handles analytics only.
Firestore non-rollback principle Firestore writes to audit collections are NEVER rolled back on Odoo sync failure. Firestore is the legal source of truth.
Field Worker Safety Capsule ID field-worker-safety. Not driver-safety or field-safety. Sector vocabulary in branch config only.
Field Worker Safety Capsule scope Generic from day one. Any branch with field workers installs the same capsule.
Identity Lock capsule ID identity-lock. Deprecated alias field-worker-identity resolves to identity-lock at provisioning.
Capsule marketplace revenue split 80% developer / 20% Citerius. First 50 developers: 90/10 for 12 months from enrollment.
Four dimension names Capital / Time / Flow / Vault are working labels only. Must be locked before developer program opens. Not blocking any branch launch.
Capsule taxonomy Locked March 2026 — see BIZ-CAPSULE-REGISTRY.md. 7 capsules generalized. Deprecated aliases supported in v1.0 manifests only.
Blockchain — Polygon chain Polygon (EVM-compatible). Per-branch contract deployment (one CiteriumMarketplace.sol per branch environment).
Blockchain — Tractus launch network Mumbai testnet for first 90 days of live operation. Mainnet after 100 confirmed transactions.
Blockchain — async anchoring Operational flow never waits on Polygon confirmation. marketplace-blockchainAgent handles all anchor calls asynchronously.
Bid window — Tractus 24 hours
Bid window — Construx 48–72 hours
Client rating at launch 1–5 aggregate. Full dimension spec before 50 live transactions.
Per-branch Polygon contract One CiteriumMarketplace.sol instance per branch per environment (dev/staging/prod).
Drone inspection — ownership model Client-owned drone. Citerius platform provides mission software, ingestion pipeline, AI review. Citerius is not in the equipment business.
bim-blueprint-vault split Split into two capsules: bim-data-vault (storage, versioning, parsing, geometry export API) and spatial-comparison-engine (point cloud ingestion, BIM mesh reference, deviation scoring, drone feed). Decision locked before spec work on either capsule.

| delivery_model field in logistics branch manifest | "longhaul" \| "lastmile". Controls Finance Agent behavior, CFDI type, routing model, Driver portal layout, and capsule defaults. Every capsule with sub-branch-specific behavior must branch on this field explicitly. Defaults to longhaul if absent. | | Lastmile Finance Agent model | ePOD-triggered revenue accrual — not escrow release. Cloud Function recognizeRevenue() fires on HANDOFF_APPROVED, writes to revenue_events (append-only), creates Odoo accrual entry, queues line item for monthly client invoice batch. | | Accounting period hard cutoff (lastmile) | Server timestamp of HANDOFF_APPROVED Firestore event determines accounting period. If timestamp falls outside the open period, entry writes to next period automatically. No user can override this. No manual backdating is possible by design. | | Lastmile CFDI type | cfdi_4_lastmile (CFDI 4.0 envío de paquetes). Not Carta Porte 3.0. Carta Porte is longhaul only. | | Density routing engine (lastmile v1) | Google OR-Tools (open source, self-hosted). VRP with time windows, 200-stop capacity in < 5s. OptimoRoute as SaaS fallback if OR-Tools integration is delayed. | | cod-treasury capsule | New capsule, lastmile only. Driver-level COD reconciliation at shift close, SPEI/CoDi auto-matching, float reporting, overnight investment trigger. Not applicable to longhaul. | | carrier-integration capsule | New capsule, lastmile only. Inbound webhook ingestion from contracted shipper platforms (MELI, Amazon Seller Services). Each platform has its own auth adapter; normalization pipeline is shared. Lastmile day-1 critical path. | | ampm reference implementation | ampm (Guadalajara MX, 217K+ deliveries/day) is the reference implementation for logistics.lastmile. All lastmile architecture decisions validated against ampm's operational requirements. | | Marketplace-discovery for lastmile | Phase 2 only. v1 lastmile operators have contracted clients (MELI, Amazon) who do not use a marketplace. Phase 2 opens spare capacity to third-party shippers (Temu, Shein, dark store operators). | | Hub operations (lastmile) | Deferred to Phase 2. Hub management (inbound scanning, sorting, driver loading, hub reconciliation) is operationally important but secondary to the finance layer and COD treasury for v1. |

| Dual data layer (lastmile analytics) | Firestore = operational ledger (legal SoT, append-only, tamper-evident). PostgreSQL/DuckDB = analytics layer (KPI computation, LLM briefing payloads, anomaly detection). Firestore feeds the columnar store via nightly batch. These are complementary — not competing. Never use Firestore for aggregated KPI queries at scale. | | cod_integrity_rate replaces review_rate (lastmile) | entity-reputation Trust Score for delivery_model: "lastmile" uses cod_integrity_rate (COD fraud resistance) instead of review_rate (not meaningful in B2B contracted delivery). Computed by cod-treasury capsule, consumed by entity-reputation. | | Revenue manipulation monitor | Ratio monitor ingresos_devengados / envíos_entregados computed weekly on DuckDB analytics layer. If WoW change > 8% without corresponding volume change, writes to revenue_anomalies/{id} (append-only), alerts Finance + Ops, blocks period close pending human review. Runs independently of the timestamp hard cutoff — catches manipulation through any remaining path. | | Morning briefing template | Canonical for all logistics.lastmile deployments. analyst-agent generates daily 6:30 AM MX WhatsApp briefing from n8n payload. Template locked in TRX-BRANCH-SPEC.md §20. Not ampm-specific. | | PUDO network (Phase 2) | pudo-network capsule (spec pending) reduces urban MX failed delivery rate (18–25% baseline) via pickup point network with WhatsApp recipient routing. Dependency: entity-reputation, carrier-integration. Lastmile only. | | First-attempt failure prediction (Phase 2) | XGBoost model on tabular features (stops, COD ratio, colonia history, courier experience, weather, WhatsApp response). Accuracy trajectory: 70–80% at launch → 88–95% at month 18. Feeds Dispatch Optimizer for proactive recipient contact. | | CETES overnight placement | cod-treasury nightly trigger recommends CETES (investible float < MXN 5M) or fondos de dinero (≥ MXN 5M). Operating reserve configurable (default MXN 2M). At MXN 43M daily float × 10.5% CETES rate ÷ 365 ≈ MXN 1.24M annual yield. | | Build start date | Tractus build begins April 15, 2026 (ACCELERATED — locked 2026-04-14 by Omicron). Runs parallel to final Personal polish. Personal launch target: May 28, 2026. World Cup 2026 kickoff: June 11, 2026. | | ampm engagement sequence | Week 1 after hire: disclose Tractus context to Pablo, propose Mode A Odoo deployment (independent of Tractus). Day 60: formal reference client proposal. Month 3–6: Tractus lastmile capsules deployed at ampm. |


§09 — Open Questions

ID Question Priority Blocks
OQ-1 Four dimension names. Capital / Time / Flow / Vault are working labels. They become the public API contract in capsule_manifest.json once the developer program opens — cannot change after that. P1 — before developer program Capsule manifest API. Not blocking any branch launch.
OQ-2 Lane Development Rep / Sales Agent for Tractus. Generic backbone Sales Agent active at launch. Logistics-specific customization deferred to Phase 2. P2 Manual client acquisition only until Phase 2.
OQ-4 Shared vs. per-branch Odoo reporting instance. Working assumption: per-branch. Shared multi-schema instance is an option when more than 3 Mode B branches exist. P2 — before Construx reporting setup Construction branch reporting setup.
OQ-5 Density routing engine for lastmile. Google OR-Tools (self-hosted, open source) vs. OptimoRoute (SaaS, faster to integrate). Working assumption: OR-Tools v1. P1 — before lastmile routing sprint lastmile dispatch optimization
OQ-6 Shared vs. separate Odoo instance for lastmile vs. longhaul. Working assumption: same instance with separate analytic.account per sub-branch for P&L segmentation. P2 Odoo reporting setup for lastmile

§10 — Pending Actions (Cross-Branch)

Action Detail Priority
Add marketplace_discovery config block to TRX branch manifest Schema defined in BIZ-MARKETPLACE-DISCOVERY.md §06 Before Tractus launch
Add marketplace_discovery config block to CNX branch manifest Same schema, construction vocabulary Before Construx launch
Deploy CiteriumMarketplace.sol to Polygon Mumbai (Tractus) tractus-dev, tractus-staging, tractus-prod — separate contract instances Before Tractus launch
Deploy CiteriumMarketplace.sol to Polygon (Construx) construx-dev, construx-staging, construx-prod — separate from Tractus Before Construx launch
Capsule ID rename pass on TRX companion docs Old IDs (cargo-audit, kyc-mx, etc.) → locked taxonomy IDs Before developer program opens
Lock OQ-1 (four dimension names) Public API contract — cannot change after developer program opens Before developer program
Write bim-data-vault capsule spec Storage, versioning, parsing, geometry export API Before Construx build
Write spatial-comparison-engine capsule spec Point cloud ingestion, BIM mesh reference, deviation scoring, drone feed integration Before Construx build
Build cod-treasury capsule Lastmile day-1 — driver reconciliation, SPEI matching, float reporting Before lastmile launch
Build carrier-integration capsule (MELI adapter) Lastmile day-1 critical path Before lastmile launch
Build carrier-integration capsule (Amazon adapter) Paired with MELI Before lastmile launch
Deploy Google OR-Tools routing service Dedicated compute (not Cloud Functions) — needed for dispatch optimizer Before lastmile routing sprint
Build recognizeRevenue() Cloud Function tractus-financeAgentRevenueRecognition — ePOD-triggered accrual with period enforcement Before lastmile finance layer sprint
Design lastmile Odoo surface (logistics_surface_lastmile.json) Revenue by client, cost per delivery by zone, COD float, period close status Before lastmile finance layer sprint
Build multi-stop Driver Portal (lastmile) Manifest view, stop-by-stop ePOD, COD screen, shift close Before lastmile launch
Resolve OQ-5 (density routing engine) OR-Tools vs. OptimoRoute Before lastmile routing sprint
Write drone-inspection capsule spec BIM→waypoint generation, mission auth, telemetry ingestion, video pipeline, multi-flight comparison Before Construx build
SA de CV incorporation Hard blocker for all MX contracts Week 1 Phase 1
Write logistics_surface_lastmile.json ampm chart of accounts: revenue by client (MELI/Amazon), cost per delivery by zone, COD float by hub, period close status Before lastmile finance sprint
Write pudo-network capsule spec Phase 2 — PUDO recruitment, scoring, failed delivery re-routing Phase 2 planning
Configure DuckDB analytics layer Nightly Firestore → columnar export pipeline. KPI views: ingresos_devengados / envíos_entregados, zone performance, COD integrity rates Before lastmile analytics sprint
Build revenue manipulation monitor revenue_anomalies collection, WoW ratio monitor, period close block Before lastmile finance sprint
Build morning briefing pipeline n8n workflow + analyst-agent system prompt per §20 of TRX-BRANCH-SPEC.md Month 1–3 lastmile
Formalize first-attempt failure prediction spec XGBoost feature set, training data requirements, integration with Dispatch Optimizer Phase 2 planning

§11 — Document Register

All documents in this project use the naming convention: {PREFIX}-{Subject}-{TYPE}-v{MAJOR}.{MINOR}-{YYMMDD}.{ext}

Prefixes: BIZ (platform-level) · TRX (Tractus) · CNX (Construx) · PRS (alaivOS Personal — not this project) · CIT (Citerius corporate/legal)
Type codes: REF · SPC · CFG · PLN · TAX · RPT · LGL · BRF

Canonical Filename Version Status Role
BIZ-PLATFORM-MASTER-REF.md (this document) 2.0 Current SoT Architecture reference for entire platform
BIZ-CAPSULE-REGISTRY.md 1.0 Current Full capsule taxonomy + all capsule specs
TRX-BRANCH-SPEC.md 1.0 Current Tractus full branch configuration + GTM
CNX-BRANCH-SPEC.md 1.0 Current Construx full branch configuration + drone inspection
BIZ-MARKETPLACE-DISCOVERY.md 1.0 Current Marketplace discovery capsule — auction, ranking, blockchain
BIZ-AGENT-CONVENTIONS.md 1.0 Current Agent conventions, naming rules, build patterns
BIZ-PlatformMaster-REF-v1.4-260313.docx 1.4 Archived → superseded by this doc Prior Word format SoT
BIZ-MarketplaceDiscovery-SPC-v1.0-260313.docx 1.0 Archived → content in BIZ-MARKETPLACE-DISCOVERY.md Prior Word format spec
CNX-BranchConfig-CFG-v1.0-260313.docx 1.0 Archived → content in CNX-BRANCH-SPEC.md Prior Word format branch config
BIZ-CapsuleTaxonomy-TAX-v1.0-260313.docx 1.0 Archived → content in BIZ-CAPSULE-REGISTRY.md Prior Word format taxonomy
TRX-MasterPlan-PLN-v1.1-260313.docx 1.1 Archived → content in TRX-BRANCH-SPEC.md Prior Word format GTM plan