RBS Ecosystem Architecture

Complete System Overview

Last Updated: January 21, 2026 Company: Red Broom Software S.A.S (RFC: RBS2201168S7) Vision: Integrated SaaS ecosystem for Mexican SMBs with wallet, payments, accounting, and industry-specific POS systems

🎯 Core Philosophy

Separation of Concerns - Each component has a specific purpose:

Colectiva - Central wallet and financial management (NOT a POS)
Constanza - Accounting, tax compliance, and AI fiscal optimization
Banxico Microservice - Payment processing infrastructure (CoDi/SPEI)
Industry POS Apps - Vertical-specific point of sale systems

No Code Duplication - Shared functionality is centralized:

Payment processing → Banxico Microservice
Wallet management → Colectiva
Accounting/tax → Constanza
Industry logic → Individual POS apps

🏗️ System Architecture

┌─────────────────────────────────────────────────────────┐
│          RED BROOM SOFTWARE S.A.S. (Holding)            │
│          RFC: RBS2201168S7 - RESICO Regime              │
└────────────────────┬────────────────────────────────────┘
                     │
         ┌───────────┴──────────┬──────────────┐
         │                      │              │
         ▼                      ▼              ▼
┌─────────────────┐    ┌──────────────┐    ┌──────────────┐
│   COLECTIVA     │    │   CONSTANZA  │    │   BANXICO    │
│   (Wallet)      │    │  (Accounting)│    │ (Payments)   │
├─────────────────┤    ├──────────────┤    ├──────────────┤
│ • Balance mgmt  │◄───┤ • Tax AI     │◄───┤ • CoDi/SPEI  │
│ • Settlements   │    │ • CFDI 4.0   │    │ • QR codes   │
│ • Payroll       │    │ • Reports    │    │ • Transfers  │
│ • Multi-currency│    │ • Compliance │    │ • Balance    │
│ • Crypto        │    │ • Nómina     │    │ • Webhooks   │
└────────┬────────┘    └──────┬───────┘    └──────┬───────┘
         │                    │                    │
         └────────────┬───────┴────────────────────┘
                      │
         ┌────────────┴─────────────┬─────────────┬─────────────┐
         ▼                          ▼             ▼             ▼
   ┌──────────┐            ┌──────────┐   ┌──────────┐   ┌──────────┐
   │ CARACOL  │            │ LA HOJA  │   │  COSMOS  │   │ PLENURA  │
   │Restaurant│            │   Café   │   │   Pet    │   │ Therapy  │
   │   POS    │            │   POS    │   │   POS    │   │   App    │
   └──────────┘            └──────────┘   └──────────┘   └──────────┘

📦 Component Details

1. COLECTIVA - Central Wallet & Financial Hub

Location: ~/Projects/colectiva-RBSTech: SvelteKit 5, Firebase, Vercel Purpose: Unified financial management platform

Core Responsibilities:

✅ Consolidated wallet across all businesses
✅ Real-time balance tracking (MXN, USD, EUR, CNY, BTC, ETH)
✅ Internal settlements (0% fee between group companies)
✅ External transactions (0.8% fee)
✅ Payroll automation and employee benefits
✅ Multi-currency portfolio management
✅ DeFi yield tracking
✅ Equity token system (internal company shares)
✅ Planning and organization tools

What It Is NOT:

❌ NOT a POS system
❌ NOT for direct customer sales
❌ NOT a payment gateway (uses Banxico for that)

Integration Points:

Calls Banxico Microservice for payment processing
Receives accounting data from Constanza
Provides balance data to all POS apps
Manages payroll for all companies

URL: TBD (in development)

2. CONSTANZA - AI Accounting & Tax Compliance

Location: ~/Projects/ConstanzaTech: SvelteKit 4, Firebase, Vercel Purpose: Automated accounting and fiscal optimization

Core Responsibilities:

✅ Multi-tenant accounting system
✅ CFDI 4.0 invoice generation and timbrado
✅ Fiscal Optimizer AI (RESICO monitoring)
✅ Automatic transaction classification (AI)
✅ SAT chart of accounts
✅ Accounting entries (Pólizas)
✅ Consolidated reports for holdings
✅ Tax reports (Balance, P&L, DIOT)
✅ Employee benefits calculator
✅ RESICO limit monitoring with alerts
✅ e.Firma/FIEL Certificate Management - Upload, validate, and securely store digital certificates
✅ Fiscal Calendar & Automatic Reminders - Track obligations with proactive alerts
✅ CFDI Automatic Download - Download invoices directly from SAT
✅ Organization Lifecycle Management - Deactivation, deletion, member management
✅ Organization Settings - Team members, roles, and organization configuration

Revenue Model:

Tier	Monthly	Annual	Target
RESICO	$8,900	$106,800	Small businesses
General	$15,000	$180,000	Medium businesses
Enterprise	$30,000	$360,000	Holdings

Integration Points:

Receives transaction data from Colectiva and POS apps
Generates fiscal reports for all companies
Feeds tax data to Colectiva for decision-making
Provides compliance alerts

URL: https://constanza-oyc4b548x-rbss-projects-204990eb.vercel.app

3. BANXICO MICROSERVICE - Payment Infrastructure

Location: ~/Projects/Banxico_payment_microserviceTech: Node.js, TypeScript, Express, PostgreSQL/SQLite Purpose: Payment processing backend (CoDi, SPEI)

Core Responsibilities:

✅ Generate CoDi QR codes (Banxico integration)
✅ Process SPEI bank transfers
✅ Manage internal coin currency (MXC)
✅ User balance tracking
✅ Transaction history
✅ Payment status polling (auto-detect payments)
✅ Webhook support for real-time notifications

Coin System (MXC):

1 MXN = 1 MXC (1:1 exchange rate)
Users deposit MXN → Get MXC coins
Transfer MXC between users (instant, free)
Withdraw MXC → Get MXN in bank account

Deployment:

URL: http://40.233.27.208:3000
Status: ✅ LIVE on Oracle Cloud
Database: PostgreSQL (or SQLite for testing)

API Endpoints:

POST   /api/v1/coins/purchase         - Generate QR code
GET    /api/v1/coins/balance/:userId  - Check balance
POST   /api/v1/transfers/user-to-user - Transfer coins
POST   /api/v1/transfers/withdraw     - Withdraw to bank
GET    /api/v1/coins/purchase/status  - Check payment status

Integration Points:

Called by Colectiva for all payment operations
Can be called directly by POS apps (if needed)
Integrates with Banxico CoDi API (Beta environment)

4. CARACOL - Restaurant POS

Location: ~/Projects/caracolTech: SvelteKit, Firebase, Vercel Purpose: Point of sale system for restaurants

Features:

✅ Table management
✅ Order taking
✅ Kitchen integration
✅ Inventory tracking
✅ Menu management
✅ Sales reports
✅ CFDI invoice generation (ecosystem stamping via Constanza)
✅ Multiple payment methods
✅ Automatic stamp retry with exponential backoff
✅ Failed stamp queue with QStash scheduler
✅ SAT Cancellation Status Query - Query SAT to check actual cancellation status
✅ Bulk Invoicing - Non-blocking bulk invoice generation with loading states
✅ Picking List Print - Print picking lists for kitchen orders
✅ Cash Register Session Validation - Mexico City timezone-aware session management

Revenue: $7,000/month licensing Status: ✅ Production (main branch)

Integration:

Sends sales data to Constanza for accounting
Uses Colectiva for payment processing (via Banxico)
Generates invoices via ecosystem stamping (Camino allocation → Constanza PAC)
QStash scheduler for failed stamp retries (every 5 minutes)

Reliability Features (Added January 2026):

Retry handler with 30s timeout and 3 immediate attempts
Failed stamp queue in Firestore with exponential backoff (5min → 15min → 45min → 2h → 6h)
Stamp allocation reversal when Constanza fails after Camino succeeds
Proper handling of PAC success code 0 (accepted, not error)
SAT status query to auto-update invoice status when cancellation completes
See: caracol/QSTASH_SETUP.md for scheduler documentation

5. LA HOJA - Café POS

Location: ~/Projects/la-hojaTech: Flutter, Firebase Purpose: Point of sale optimized for coffee shops

Features:

✅ Quick sale interface
✅ Inventory (beans, milk, supplies)
✅ Loyalty programs
✅ Prepaid cards
✅ Sales reports

Status: 🚧 In development Base: Same codebase as Caracol, optimized for cafés

Integration:

Same pattern as Caracol
Shares accounting/payment infrastructure

6. COSMOS PET - Veterinary POS

Location: ~/Projects/Cosmos-petTech: Flutter, Firebase Purpose: Point of sale for veterinary clinics

Features:

✅ Patient records
✅ Appointment scheduling
✅ Inventory (medications, supplies)
✅ Service billing
✅ Medical history

Status: 🚧 In development

Integration:

Same pattern as other POS apps
Specialized for veterinary workflows

7. CAMINO CRM - Marketing & Communications Hub

Location: ~/Projects/camino/crmTech: SvelteKit 5, Supabase, Vercel Purpose: CRM, marketing automation, and ecosystem communications

Core Responsibilities:

✅ OAuth2 SSO Provider for entire ecosystem
✅ Email automation (Resend integration)
✅ WhatsApp Business API integration
✅ Voice AI outbound calls
✅ Lead management and nurturing
✅ Social media campaign management
✅ Landing page builder
✅ Team collaboration with approval workflows
✅ Subscription management across ecosystem apps
✅ Developer session handling for cross-app access

Key APIs:

POST /api/internal/email - Send templated emails
POST /api/internal/whatsapp - Send WhatsApp messages
POST /api/ecosystem/voice/onboard - Enable Voice AI
GET/POST /oauth/* - OAuth2 SSO endpoints

Integration Points:

All ecosystem apps use Camino for notifications
Provides SSO for Constanza, Caracol, La Hoja, Cosmos Pet, Colectiva
Manages subscription billing across all apps
Tracks stamp allocations for ecosystem invoicing

Status: ✅ Production URL: https://camino-crm.vercel.app

8. PLENURA - Therapy Booking Platform

Location: ~/Projects/plenuraTech: Go backend, Flutter frontend, Firebase Purpose: Marketplace for therapy services

Features:

✅ Therapist profiles
✅ Service booking
✅ Availability management
✅ Client reviews
✅ Payment processing (integrated with Banxico)

Status: ✅ Backend complete, frontend in development

Integration:

Uses Banxico Microservice for payments
Coin-based system (MXC) for therapist payments
Clients deposit → Pay therapists → Therapists withdraw

Payment Flow:

Client deposits 500 MXN → Gets 500 MXC
Client books therapy (200 MXN) → Transfers 200 MXC to therapist
Therapist withdraws 200 MXC → Gets 200 MXN in bank

🔄 Data Flow & Integration Patterns

Payment Flow (Standardized)

Any App (POS/Plenura)
    ↓
Colectiva Wallet
    ↓
Banxico Microservice
    ↓
Banxico CoDi API → User's Bank

Accounting Flow

Transaction (POS/Wallet)
    ↓
Constanza (Classification)
    ↓
Accounting Entry (Póliza)
    ↓
Financial Reports

Settlement Flow (Internal Transfers)

Source Company (via Colectiva)
    ↓
Colectiva Wallet (0% fee)
    ↓
Destination Company

🎨 Design Principles

1. Single Source of Truth

Payments: Banxico Microservice only
Wallet: Colectiva only
Accounting: Constanza only
Industry Logic: Individual POS apps

2. API-First Architecture

All components expose REST APIs
Authentication via Firebase
Standardized error handling
Comprehensive documentation

3. Multi-Tenancy

Each business is a separate tenant
Shared infrastructure
Isolated data
Centralized billing

4. Fiscal Compliance

All transactions recorded
CFDI 4.0 compliant
SAT catalog integration
Automatic tax calculations

⏰ Scheduled Jobs Architecture

The ecosystem uses two cron systems based on database technology:

Camino pg_cron (Supabase)

For ecosystem-wide and Supabase-based jobs:

Category	Jobs	Examples
Ecosystem-wide	3	`calculate_billing`, `expire_trials`, `reset_usage_counters`
Cross-app	1	`sync_constanza_invoices`
Camino-internal	7	`invoice_retry`, `nurture_emails`, `voice-outbound`

App QStash (Upstash)

For Firebase-based app-internal jobs:

App	Jobs	Examples
La Hoja	3	`mancha-retry`, `reset-allocations`, `cleanup-dead-letter`
Caracol	1	`stamp-retry` (failed invoice stamp retries)

Decision Criteria

┌─────────────────────────────────────────────────────┐
│ Is the job ecosystem-wide or cross-app?            │
│   YES → Use Camino pg_cron                          │
│   NO  ↓                                             │
├─────────────────────────────────────────────────────┤
│ Does the app use Supabase?                          │
│   YES → Use Camino pg_cron (convenience)            │
│   NO  ↓                                             │
├─────────────────────────────────────────────────────┤
│ App uses Firebase → Use App's own QStash            │
└─────────────────────────────────────────────────────┘

See: /home/brillo/Projects/CRON_ARCHITECTURE_ANALYSIS.md for detailed analysis.

🔐 Security & Access Control

Authentication

Firebase Authentication (all apps)
JWT tokens for API calls
Role-based access control (RBAC)

Data Isolation

Firestore security rules
Organization-level isolation
User permission layers

Payment Security

PCI DSS considerations
Encrypted credentials
Secure API keys
Webhook signatures

Scheduled Job Security

QStash signature verification for external schedulers
pg_cron runs within Supabase (trusted environment)
API keys stored in environment variables (never in code)

💰 Revenue Model

RBS Income Streams

Constanza Memberships: $8,900 - $30,000/month
POS Licensing: $7,000+/month
Transaction Fees: 0.8% on external payments
Additional Services: Consulting, training, custom features

Cost Structure

Hosting: ~$200/month (Firebase, Vercel, Oracle Cloud)
Banxico API: Minimal (beta testing)
Development: Internal
PAC (CFDI): Per invoice usage

📊 Current Status Dashboard

Component	Status	URL	Revenue
Colectiva	🚧 Development	TBD	Planned
Constanza	✅ Production	Live	$0 (launching Dec)
Banxico Service	✅ Production	http://40.233.27.208:3000	N/A (infrastructure)
Caracol	✅ Production	Private	$7,000/month
La Hoja	🚧 Development	TBD	Planned
Cosmos Pet	🚧 Development	TBD	Planned
Plenura	🟡 Backend Ready	Backend live	Planned

Total Current Revenue: ~$384,000/year RESICO Limit: $3,500,000/year Utilization: 10.97% Available Growth: $3,116,000

🚀 Development Workflow

Adding New Features

Identify which component owns the feature
Check if functionality exists elsewhere (avoid duplication)
Use existing services (Banxico, Constanza, Colectiva)
Document integration points

Creating New POS App

Clone base POS structure (Caracol)
Customize industry-specific features
Integrate with Colectiva for payments
Send transactions to Constanza for accounting
Follow multi-tenant pattern

Testing Integration

Test each component independently
Test integration points
End-to-end flow testing
Production deployment

📁 Directory Structure

~/Projects/
├── ECOSYSTEM_ARCHITECTURE.md     ← THIS FILE
├── MASTER_ROADMAP.md              ← Product roadmap
├── CONTEXTO_COMPLETO_ECOSISTEMA_RBS.md  ← Detailed context
│
├── colectiva-RBS/                 ← Wallet & Financial Hub
│   ├── ECOSYSTEM_CONTEXT.md       ← How Colectiva fits in ecosystem
│   └── [app code]
│
├── Constanza/                     ← Accounting & Tax
│   ├── ECOSYSTEM_CONTEXT.md       ← How Constanza fits in ecosystem
│   └── [app code]
│
├── Banxico_payment_microservice/  ← Payment Infrastructure
│   ├── ECOSYSTEM_CONTEXT.md       ← How Banxico fits in ecosystem
│   └── [microservice code]
│
├── caracol/                       ← Restaurant POS
│   ├── ECOSYSTEM_CONTEXT.md       ← How Caracol fits in ecosystem
│   └── [app code]
│
├── la-hoja/                       ← Café POS
│   ├── ECOSYSTEM_CONTEXT.md       ← How La Hoja fits in ecosystem
│   └── [app code]
│
├── Cosmos-pet/                    ← Veterinary POS
│   ├── ECOSYSTEM_CONTEXT.md       ← How Cosmos fits in ecosystem
│   └── [app code]
│
└── plenura/                       ← Therapy Platform
    ├── ECOSYSTEM_CONTEXT.md       ← How Plenura fits in ecosystem
    └── [app code]

📝 Documentation Standards

Each project MUST have:

ECOSYSTEM_CONTEXT.md - How it fits in the larger system
README.md - Project-specific documentation
API documentation - If it exposes APIs
Integration guides - How to connect with other components

🎯 Next Steps

Immediate Priorities

✅ Complete Banxico-Plenura integration
🚧 Finish Colectiva wallet core features
🚧 Deploy Constanza for first client (December)
📋 La Hoja MVP completion

Q1 2026

Launch Constanza memberships
Onboard 5-10 RESICO clients
Complete Plenura frontend
Launch La Hoja

Q2 2026

Cosmos Pet beta
Expand Caracol features
International payment support
Crypto portfolio in Colectiva

🤝 Contributing

When working on any component:

Read this document first
Read the component's ECOSYSTEM_CONTEXT.md
Understand dependencies on other services
Follow integration patterns
Document changes
Test integrations

📞 Support

Technical Lead: Julio Sitges
Email: juliositgespomares@gmail.com
Company: Red Broom Software S.A.S.
RFC: RBS2201168S7

Remember: We're building a cohesive ecosystem, not isolated apps. Every component serves a specific purpose and integrates with the whole.

RBS Ecosystem Architecture ​

Complete System Overview ​

🎯 Core Philosophy ​

🏗️ System Architecture ​

📦 Component Details ​

1. COLECTIVA - Central Wallet & Financial Hub ​

2. CONSTANZA - AI Accounting & Tax Compliance ​

3. BANXICO MICROSERVICE - Payment Infrastructure ​

4. CARACOL - Restaurant POS ​

5. LA HOJA - Café POS ​

6. COSMOS PET - Veterinary POS ​

7. CAMINO CRM - Marketing & Communications Hub ​

8. PLENURA - Therapy Booking Platform ​

🔄 Data Flow & Integration Patterns ​

Payment Flow (Standardized) ​

Accounting Flow ​

Settlement Flow (Internal Transfers) ​

🎨 Design Principles ​

1. Single Source of Truth ​

2. API-First Architecture ​

3. Multi-Tenancy ​

4. Fiscal Compliance ​

⏰ Scheduled Jobs Architecture ​

Camino pg_cron (Supabase) ​

App QStash (Upstash) ​

Decision Criteria ​

🔐 Security & Access Control ​

Authentication ​

Data Isolation ​

Payment Security ​

Scheduled Job Security ​

💰 Revenue Model ​

RBS Income Streams ​

Cost Structure ​

📊 Current Status Dashboard ​

🚀 Development Workflow ​

Adding New Features ​

Creating New POS App ​

Testing Integration ​

📁 Directory Structure ​

📝 Documentation Standards ​

🎯 Next Steps ​

Immediate Priorities ​

Q1 2026 ​

Q2 2026 ​

🤝 Contributing ​

📞 Support ​

RBS Ecosystem Architecture

Complete System Overview

🎯 Core Philosophy

🏗️ System Architecture

📦 Component Details

1. COLECTIVA - Central Wallet & Financial Hub

2. CONSTANZA - AI Accounting & Tax Compliance

3. BANXICO MICROSERVICE - Payment Infrastructure

4. CARACOL - Restaurant POS

5. LA HOJA - Café POS

6. COSMOS PET - Veterinary POS

7. CAMINO CRM - Marketing & Communications Hub

8. PLENURA - Therapy Booking Platform

🔄 Data Flow & Integration Patterns

Payment Flow (Standardized)

Accounting Flow

Settlement Flow (Internal Transfers)

🎨 Design Principles

1. Single Source of Truth

2. API-First Architecture

3. Multi-Tenancy

4. Fiscal Compliance

⏰ Scheduled Jobs Architecture

Camino pg_cron (Supabase)

App QStash (Upstash)

Decision Criteria

🔐 Security & Access Control

Authentication

Data Isolation

Payment Security

Scheduled Job Security

💰 Revenue Model

RBS Income Streams

Cost Structure

📊 Current Status Dashboard

🚀 Development Workflow

Adding New Features

Creating New POS App

Testing Integration

📁 Directory Structure

📝 Documentation Standards

🎯 Next Steps

Immediate Priorities

Q1 2026

Q2 2026

🤝 Contributing

📞 Support