CONFIDENTIAL — AZ1.AI Inc. — Internal Use Only This document contains proprietary and confidential information. Unauthorized distribution, reproduction, or disclosure is strictly prohibited.

CFS-004: Technical Architecture

---

1. Executive Summary

This document defines the system architecture for the CODITECT Financial Suite — an AI-first, multi-national, multi-tenant SaaS financial platform. The architecture is designed for 30+ jurisdiction compliance, 10,000+ concurrent users, sub-200ms API response times, and AI-integrated financial workflows.

---

2. Architecture Principles

Principle	Description
AI-First	AI is an architectural component, not a bolt-on feature
Multi-Tenant by Default	PostgreSQL RLS, tenant isolation at every layer
API-First	REST + GraphQL, versioned, documented, all UI through APIs
Event-Driven	Async processing, CQRS for read-heavy reporting workloads
Cloud-Native	Kubernetes, GCP primary, multi-cloud capable
Compliance-by-Design	Audit trail, encryption, regulatory hooks built into core
Domain-Driven Design	Bounded contexts per financial module

---

3. System Context (C4 Level 1)

---

4. Container Diagram (C4 Level 2)

---

5. Technology Stack

Layer	Technology	Rationale
Frontend	React 18 + TypeScript + Ant Design 5	Proven enterprise UI, existing prototype, rich component library
API Gateway	Kong or Envoy	Rate limiting, auth, routing, observability
Backend Services	Python (FastAPI)	Rapid development, AI/ML ecosystem, team expertise
Real-time	WebSocket (FastAPI)	Live dashboards, notifications
Database	PostgreSQL 16	RLS, JSONB, partitioning, mature ecosystem
Time-Series	TimescaleDB extension	Financial time-series (balances, rates, metrics)
Vector Store	pgvector extension	AI embeddings for NLQ and document similarity
Cache	Redis 7	Session management, rate limiting, hot data cache
Message Broker	NATS	Lightweight, high-throughput event streaming
Object Storage	Google Cloud Storage	Documents, backups, exports
AI/ML Runtime	Python + vLLM + Ollama	Local model inference for sensitive data
LLM API	Claude API (Anthropic)	Complex reasoning, NLQ, financial analysis
OCR	Tesseract + EasyOCR	Multi-language document processing
Layout Analysis	LayoutLM v3	Document structure understanding
Forecasting	NeuralProphet + statsforecast	Time-series prediction with confidence intervals
Search	Meilisearch	Full-text search across financial data
Infrastructure	GKE (Google Kubernetes Engine)	Auto-scaling, managed Kubernetes
IaC	Terraform	Infrastructure as Code, multi-environment
CI/CD	GitHub Actions → ArgoCD	GitOps deployment pipeline
Monitoring	Prometheus + Grafana + OpenTelemetry	Metrics, dashboards, distributed tracing
Logging	Loki + Grafana	Centralized log aggregation
Secrets	GCP Secret Manager	Secrets rotation, access control

---

6. Data Architecture

6.1 Multi-Tenant Model

PostgreSQL Cluster
├── Shared schema with RLS policies
├── tenant_id column on ALL tables
├── RLS policy: current_setting('app.tenant_id')
├── Connection pooling: PgBouncer
└── Read replicas for reporting workloads

Tenant Context Flow:

1. Request arrives at API Gateway
2. JWT decoded → tenant_id extracted
3. Database session: SET app.tenant_id = '{uuid}'
4. RLS policies automatically filter all queries
5. No application-level tenant filtering needed (defense in depth)

6.2 Core GL Schema (Simplified)

-- Entity Hierarchy
CREATE TABLE gl_entities (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    parent_entity_id UUID REFERENCES gl_entities(id),
    entity_type TEXT NOT NULL, -- 'organization', 'legal_entity', 'division'
    name TEXT NOT NULL,
    functional_currency CHAR(3) NOT NULL,
    reporting_currency CHAR(3),
    fiscal_year_start_month INTEGER DEFAULT 1,
    country_code CHAR(2) NOT NULL,
    tax_registration_id TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 3-Slot Journal Lines
CREATE TABLE gl_journal_lines (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL,
    entity_id UUID NOT NULL REFERENCES gl_entities(id),
    journal_entry_id UUID NOT NULL,
    account_id UUID NOT NULL,
    -- Transaction currency (original)
    transaction_currency CHAR(3) NOT NULL,
    transaction_debit NUMERIC(19,4) DEFAULT 0,
    transaction_credit NUMERIC(19,4) DEFAULT 0,
    -- Functional currency (entity's home currency)
    functional_currency CHAR(3) NOT NULL,
    functional_debit NUMERIC(19,4) DEFAULT 0,
    functional_credit NUMERIC(19,4) DEFAULT 0,
    functional_exchange_rate NUMERIC(19,10),
    -- Reporting currency (group/consolidation)
    reporting_currency CHAR(3),
    reporting_debit NUMERIC(19,4) DEFAULT 0,
    reporting_credit NUMERIC(19,4) DEFAULT 0,
    reporting_exchange_rate NUMERIC(19,10),
    -- Dimensions
    cost_center_id UUID,
    department_id UUID,
    project_id UUID,
    -- Metadata
    description TEXT,
    fiscal_period_id UUID NOT NULL,
    posted_at TIMESTAMPTZ DEFAULT NOW()
);

6.3 Partitioning Strategy

Table	Partition Key	Strategy
gl_journal_lines	fiscal_period_id	Range by period
gl_audit_log	created_at	Range by month
documents	tenant_id	Hash by tenant
bank_transactions	import_date	Range by month

6.4 Data Residency

Per-tenant database region selection:

• Americas: us-central1 (Iowa), southamerica-east1 (São Paulo)
• Europe: europe-west1 (Belgium), europe-west3 (Frankfurt)
• APAC: asia-south1 (Mumbai), australia-southeast1 (Sydney)

---

7. AI/ML Architecture

7.1 Document Intelligence Pipeline

Document Upload
    │
    ▼
┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Ingestion   │────▶│  OCR Engine   │────▶│ Layout Analysis  │
│ (PDF/IMG/XML)│     │(Tesseract/   │     │ (LayoutLM v3)   │
│              │     │ EasyOCR)     │     │                  │
└─────────────┘     └──────────────┘     └────────┬────────┘
                                                   │
                                                   ▼
┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Learning    │◀────│  GL Coding    │◀────│Entity Extraction │
│  Loop        │     │(ML + Rules)  │     │(NER + Custom)   │
│(corrections) │     │              │     │                  │
└─────────────┘     └──────┬───────┘     └─────────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │  Confidence   │──▶ High: Auto-post
                    │  Scoring      │──▶ Medium: Review queue
                    │               │──▶ Low: Manual processing
                    └──────────────┘

7.2 NLQ Architecture

User Query (natural language)
    │
    ▼
Intent Classification (Claude API)
    │
    ▼
SQL Generation (Claude API + guardrails)
    │
    ▼
Sandboxed Execution (read-only replica, row limit, timeout)
    │
    ▼
Result Processing → Natural Language Response (Claude API)

Safety Guardrails:

• Read-only database connection (no mutations)
• Result size limit (10,000 rows max)
• Query timeout (30 seconds)
• Sensitive column masking
• Query audit logging

7.3 LLM Routing Strategy

Task Type	Model	Rationale
Complex reasoning (NLQ, analysis)	Claude API	Best reasoning capability
Document classification	Local Mistral (Ollama)	High-volume, low-latency, privacy
Entity extraction	Custom NER + LayoutLM	Domain-specific accuracy
Forecasting	NeuralProphet	Purpose-built time-series
Anomaly detection	Statistical + Isolation Forest	Interpretable, fast

---

8. API Architecture

8.1 REST API

/api/v1/
├── /auth/                    # Authentication
├── /entities/                # Entity management
├── /gl/
│   ├── /accounts/           # Chart of Accounts
│   ├── /journal-entries/    # Journal entries
│   ├── /periods/            # Fiscal periods
│   ├── /trial-balance/      # Trial balance
│   └── /financial-statements/ # BS, IS, CF
├── /ap/
│   ├── /vendors/            # Vendor master
│   ├── /invoices/           # AP invoices
│   └── /payments/           # Payments
├── /ar/
│   ├── /customers/          # Customer master
│   └── /invoices/           # AR invoices
├── /tax/                     # Tax calculations
├── /bank-rec/               # Bank reconciliation
├── /documents/              # Document intelligence
├── /fpa/                    # FP&A queries
├── /consolidation/          # Consolidation
├── /practice/               # Practice management
└── /reports/                # Report generation

8.2 GraphQL (Reporting)

GraphQL for complex financial queries with nested drill-down:

• Trial balance → account details → journal entries → source documents
• Consolidation → entity contributions → elimination details
• Dashboard → KPI → trend → underlying transactions

---

9. Integration Architecture

9.1 Connector Framework

External System
    │
    ▼
┌─────────────────┐
│  Adapter Layer   │  ← System-specific protocol (REST, SOAP, file, etc.)
├─────────────────┤
│  Transform Layer │  ← Normalize to CODITECT canonical model
├─────────────────┤
│  Sync Engine     │  ← Scheduled sync, CDC, or real-time
├─────────────────┤
│  Conflict Res    │  ← Last-write-wins, manual review, or merge
└─────────────────┘

9.2 Integration Matrix

System	Protocol	Sync Mode	Phase
Totvs Protheus	REST API	Scheduled (15 min)	1
Omie	REST API	Scheduled (15 min)	1
Open Finance BR	REST + OAuth	Real-time (webhook)	1
Plaid	REST API	Daily + on-demand	1
Pix (BACEN)	ISO 20022	Real-time	1
ACH (US)	NACHA file	Batch (daily)	1
SPED	XML file generation	On-demand	1
SAP	RFC/BAPI or OData	Scheduled	2
SEPA	ISO 20022 XML	Batch (daily)	2
CFDI (Mexico)	XML + PAC	Real-time	2
FEC (France)	CSV (18 fields)	On-demand	3

---

10. Security Architecture

10.1 Zero-Trust Model

Internet → WAF → Load Balancer → API Gateway → Service Mesh → Service → Database
           │        │                │              │           │         │
           ▼        ▼                ▼              ▼           ▼         ▼
        DDoS    TLS 1.3         OAuth 2.0      mTLS        RBAC     RLS + TDE
        protection  termination    + JWT         between     + ABAC    encryption
                                                 services

10.2 Encryption

Layer	Method
In transit	TLS 1.3 (all connections)
At rest (database)	AES-256-GCM (PostgreSQL TDE)
At rest (files)	AES-256 (GCS server-side encryption)
At rest (backups)	AES-256 (separate key)
Key management	GCP Cloud KMS (FIPS 140-2 Level 3)
Application-level	Field-level encryption for PII (tax IDs, bank accounts)

10.3 Audit Trail

• Append-only table (gl_audit_log)
• Hash-chained entries (each entry includes hash of previous)
• Immutable (no UPDATE or DELETE, enforced by trigger)
• Partitioned by month for performance
• 7-10 year retention (jurisdiction-dependent)
• Tamper detection via hash chain verification

---

11. Infrastructure & Deployment

11.1 Kubernetes Architecture

GKE Cluster
├── Namespace: coditect-prod
│   ├── Deployment: api-gateway (3 replicas, HPA)
│   ├── Deployment: gl-service (3 replicas, HPA)
│   ├── Deployment: ap-service (2 replicas, HPA)
│   ├── Deployment: ar-service (2 replicas, HPA)
│   ├── Deployment: document-intelligence (2 replicas, GPU node pool)
│   ├── Deployment: nlq-engine (2 replicas, GPU optional)
│   ├── StatefulSet: postgresql-primary (1 replica)
│   ├── StatefulSet: postgresql-replicas (2 replicas)
│   ├── StatefulSet: redis (3 replicas, sentinel)
│   └── Deployment: nats (3 replicas, JetStream)
├── Namespace: coditect-monitoring
│   ├── Prometheus
│   ├── Grafana
│   └── Loki
└── Namespace: coditect-jobs
    ├── CronJob: exchange-rate-sync (hourly)
    ├── CronJob: balance-cache-refresh (15 min)
    └── CronJob: backup (6 hours)

11.2 CI/CD Pipeline

GitHub Push → GitHub Actions → Build + Test → Container Registry → ArgoCD → GKE
                                    │
                                    ├── Unit tests
                                    ├── Integration tests
                                    ├── SAST (Semgrep)
                                    ├── Dependency scan (Snyk)
                                    └── Container scan (Trivy)

11.3 Deployment Strategy

• Blue-green for major releases
• Canary (5% → 25% → 100%) for minor releases
• Rolling for patches
• Database migrations: forward-compatible, zero-downtime

---

12. Performance & Scalability

Metric	Target	Strategy
API response (p95)	<200ms	Connection pooling, Redis cache, query optimization
Report generation	<5s (standard), <30s (consolidation)	Materialized views, pre-computed balances
Document OCR	<10s per page	GPU acceleration, parallel processing
Concurrent users	10,000+	HPA auto-scaling, read replicas
Monthly transactions	1M+ per tenant	Table partitioning, async batch processing
Database connections	PgBouncer (100 connections → 10,000 concurrent requests)	Connection pooling

Scalability Path

Scale Point	Architecture Change
100 tenants	Single region, single cluster
1,000 tenants	Read replicas, enhanced caching
10,000 tenants	Multi-region, database sharding by tenant group
100,000 tenants	Dedicated clusters for enterprise, edge compute

---

13. Disaster Recovery

Metric	Target
RPO (Recovery Point Objective)	<1 hour
RTO (Recovery Time Objective)	<4 hours
Backup frequency	Every 6 hours (full), continuous WAL archiving
Backup retention	30 days (hot), 1 year (cold), 7 years (archive for compliance)
Failover	Automatic to standby region (manual trigger)
DR testing	Quarterly tabletop exercise, annual full failover test

---

Hal Casteel CEO/CTO, AZ1.AI Inc.

Copyright © 2026 AZ1.AI Inc. All rights reserved. Unauthorized distribution or reproduction is strictly prohibited.