C4 Architecture Documentation

Purpose: Complete C4 model documentation for FP&A Platform Methodology: Simon Brown's C4 Model (Context, Container, Component, Code) Format: Mermaid diagrams with narratives

Level 1: System Context Diagrams

C4-CTX-001: FP&A Platform System Context

Diagram

Narrative

The FP&A Platform serves multiple user personas across different organizational roles and geographic markets:

Primary Users:

CFO/Finance Leaders: Strategic oversight, dashboard consumption, budget approval
FP&A Analysts: Day-to-day forecasting, variance analysis, report generation
Controllers: Month-end close orchestration, journal entry approval, compliance
Contadores (Brazil-specific): Multi-client management, SPED generation, fiscal compliance

External Systems:

ERP Systems: Source of truth for transactional data (GL, AP/AR, inventory)
Banking Systems: Real-time cash positions, transaction feeds for reconciliation
Regulatory Systems: Filing destinations for tax and compliance documents
CRM/Revenue Platforms: Sales and revenue data for forecasting and analysis

Key Interactions:

Bi-directional data flow with ERPs (extract + optional journal posting)
Real-time or near-real-time banking data synchronization
Automated regulatory filing submission with status tracking
Revenue data enrichment from CRM for pipeline forecasting

C4-CTX-002: Multi-Tenant Architecture Context

Diagram

Narrative

The platform supports two primary deployment patterns:

Single-Company Tenants: Traditional US/global companies where one tenant = one company
Multi-Client Tenants: Brazilian "contador" model where one tenant serves multiple companies

Row-Level Security (RLS) ensures complete data isolation at the database level. Even within a multi-client tenant, each client's data is segregated with appropriate access controls.

Level 2: Container Diagrams

C4-CON-001: FP&A Platform Containers

Diagram

Narrative

The platform follows a microservices architecture with clear separation of concerns:

Presentation Layer:

Web Application: React-based SPA with responsive design for desktop and mobile
API Gateway: Central entry point handling auth, rate limiting, and routing

Application Services:

Auth Service: Keycloak for identity + OpenFGA for fine-grained authorization
General Ledger Service: Core accounting (COA, journal entries, trial balance)
Planning Service: Budget management, forecasting, scenario modeling
Reporting Service: Financial statement generation, KPI dashboards
Reconciliation Service: Bank matching, intercompany reconciliation
Compliance Service: Regulatory filing, audit trail management

AI/ML Services:

AI Orchestrator: LangGraph-based agent coordination
LLM Service: Self-hosted DeepSeek-R1 for variance explanations, NLG
Forecast Engine: NeuralProphet ensemble for predictions

Data Layer:

PostgreSQL: Primary OLTP with Row-Level Security
TimescaleDB: Time-series data (forecasts, metrics)
immudb: Cryptographic audit trail
Redis: Caching and session storage
pgvector: AI embeddings

Integration Layer:

Airbyte: ELT connector orchestration
Kafka: Event-driven messaging

C4-CON-002: AI Agent Architecture Containers

Diagram

Narrative

The AI agent architecture implements the Orchestrator-Workers pattern from Anthropic's agent taxonomy:

Orchestrator Agent:

Receives user requests via API
Classifies intent using fine-tuned classifier
Routes to appropriate specialized agent
Coordinates multi-agent workflows
Maintains conversation context

Specialized Agents:

Reconciliation Agent: Bank matching logic, exception identification
Variance Analysis Agent: Budget vs actual calculations, driver identification
Forecasting Agent: Model selection, prediction generation
Compliance Agent: Control testing automation, evidence gathering
NLG Agent: Financial commentary writing, report generation

Supporting Infrastructure:

State Checkpointer: PostgreSQL-based state persistence for long-running workflows
Agent Memory: Vector store for RAG + Redis for session caching

ML Services:

LLM Service: vLLM serving DeepSeek-R1-32B with INT8 quantization
Forecast ML: NeuralProphet with ARIMA/XGBoost fallbacks
Anomaly Detection: PyOD for transaction and variance outliers
Intent Classifier: Fine-tuned BERT for routing decisions

Level 3: Component Diagrams

C4-CMP-001: General Ledger Service Components

Diagram

Narrative

Core Components:

COA Manager
- CRUD operations for chart of accounts
- LTREE-based hierarchy management
- Account type validation (Asset, Liability, Equity, Revenue, Expense)
- Account activation/deactivation
Journal Entry Processor
- Entry creation and validation
- Multi-line entry handling
- Posting to general ledger
- Reversal generation
- Recurring entry processing
Trial Balance Generator
- Period-end balance calculation
- Account hierarchy rollups
- Comparative period support
- Dimension filtering
Financial Statement Builder
- Balance sheet generation
- Income statement generation
- Cash flow statement (indirect method)
- Statement of equity
Period Manager
- Accounting period maintenance
- Soft close (warn on posting)
- Hard close (prevent posting)
- Year-end close process
- Retained earnings calculation
Dimension Manager
- Cost center management
- Department hierarchy
- Project tracking
- Custom dimension support

Supporting Components:

Validation Engine: Business rules enforcement, debit/credit balance
Approval Workflow: Configurable approval chains, delegation
Audit Logger: Every change logged to immudb with Merkle proof

C4-CMP-002: Planning Service Components

Diagram

Narrative

Budget Components:

Budget Manager
- Annual, quarterly, rolling budget creation
- Version control (Draft, Submitted, Approved, Locked)
- Top-down and bottom-up consolidation
- Zero-based budgeting support
Driver Calculator
- Headcount-driven expense modeling
- Revenue-driven variable costs
- Statistical accounts (units, FTEs)
- Driver relationships and formulas
Allocation Engine
- Step-down allocation methods
- Direct and reciprocal allocation
- Activity-based costing support
- Allocation rule versioning

Forecasting Components:

Forecast Engine
- 13-week rolling cash flow forecasts
- 18-month P&L forecasts
- Confidence interval calculation
- Actual-to-forecast comparison
Ensemble Selector
- Model performance evaluation
- Automatic fallback selection
- Accuracy tracking per account
Scenario Modeler
- What-if scenario creation
- Sensitivity analysis
- Monte Carlo simulation
- Scenario comparison reports

Integration Components:

Excel Interface: Template-based import/export for familiar workflow
Variance Calculator: Real-time BvA with drill-down capability
Dagster: ML pipeline orchestration for forecast generation

C4-CMP-003: Reconciliation Service Components

Diagram

Narrative

Reconciliation Types:

Bank Reconciliation
- Import bank statements (OFX, CSV, API)
- Match to GL cash transactions
- Handle timing differences
- Outstanding check tracking
- Deposits in transit
Intercompany Reconciliation
- Match transactions across entities
- Currency conversion handling
- Elimination entry suggestions
- Dispute workflow
Subledger Reconciliation
- AP aging to GL payables
- AR aging to GL receivables
- Inventory to GL inventory

Matching Components:

Match Engine
- Exact match (amount, date, reference)
- One-to-many matching
- Many-to-many matching
- Tolerance-based matching
ML Matcher
- Historical pattern learning
- Fuzzy text matching
- Confidence scoring
- Continuous learning from user corrections
Exception Manager
- Unmatched item identification
- Research workflow
- Adjustment entry suggestion
- Escalation routing

Configuration:

Rule Builder: Custom matching logic per account
Threshold Manager: Tolerance amounts, aging thresholds

Level 4: Code Diagrams

C4-CODE-001: Journal Entry Processor Sequence

Diagram

Narrative

The journal entry creation follows a strict sequence ensuring data integrity:

Authorization: OpenFGA verifies user has create permission on journal_entry resource
Validation: Multiple business rules checked:
- Debits equal credits
- All accounts exist and are active
- Accounting period is open
- Amount limits respected
Transaction: Single database transaction ensures atomicity
Audit: Entry logged to immudb with cryptographic hash
Events: Kafka event published for downstream processing

C4-CODE-002: LangGraph Variance Analysis Workflow

Diagram

LangGraph Implementation

from langgraph.graph import StateGraph, END
from langgraph.checkpoint.postgres import PostgresCheckpoint
from typing import TypedDict, Annotated
import operator

class VarianceState(TypedDict):
    request_id: str
    tenant_id: str
    period: str
    budget_data: dict
    actual_data: dict
    variances: list
    material_variances: list
    driver_analysis: dict
    commentary: str
    compliance_status: str
    approval_status: str
    error: str | None

def classify_request(state: VarianceState) -> VarianceState:
    """Classify if request is variance analysis"""
    # Intent classification logic
    return state

def load_budget_data(state: VarianceState) -> VarianceState:
    """Load budget data for the period"""
    # Query budget_lines for period
    return {**state, "budget_data": budget_data}

def load_actual_data(state: VarianceState) -> VarianceState:
    """Load actual data from GL"""
    # Query account_balances for period
    return {**state, "actual_data": actual_data}

def calculate_variances(state: VarianceState) -> VarianceState:
    """Calculate budget vs actual variances"""
    variances = []
    for account in state["budget_data"]:
        budget = state["budget_data"][account]
        actual = state["actual_data"].get(account, 0)
        variance = actual - budget
        variance_pct = (variance / budget * 100) if budget else 0
        variances.append({
            "account": account,
            "budget": budget,
            "actual": actual,
            "variance": variance,
            "variance_pct": variance_pct
        })
    return {**state, "variances": variances}

def identify_material_variances(state: VarianceState) -> VarianceState:
    """Filter for material variances (>5% or >$10K)"""
    material = [
        v for v in state["variances"]
        if abs(v["variance_pct"]) > 5 or abs(v["variance"]) > 10000
    ]
    return {**state, "material_variances": material}

def analyze_drivers(state: VarianceState) -> VarianceState:
    """Use LLM to analyze variance drivers"""
    # LLM call to identify root causes
    driver_analysis = llm.analyze_drivers(state["material_variances"])
    return {**state, "driver_analysis": driver_analysis}

def generate_commentary(state: VarianceState) -> VarianceState:
    """Generate natural language commentary"""
    commentary = llm.generate_commentary(
        variances=state["material_variances"],
        drivers=state["driver_analysis"]
    )
    return {**state, "commentary": commentary}

def compliance_check(state: VarianceState) -> VarianceState:
    """Check if commentary meets compliance requirements"""
    # Validate no forward-looking statements without disclaimers
    # Validate attribution to sources
    return {**state, "compliance_status": "passed"}

def should_require_approval(state: VarianceState) -> str:
    """Determine if human review is required"""
    if state["compliance_status"] == "failed":
        return "human_review"
    if any(v["variance"] > 100000 for v in state["material_variances"]):
        return "human_review"
    return "auto_approve"

def human_review(state: VarianceState) -> VarianceState:
    """Checkpoint for human review"""
    # This node triggers a checkpoint and waits
    return state

def format_output(state: VarianceState) -> VarianceState:
    """Format final output"""
    return state

# Build the graph
workflow = StateGraph(VarianceState)

workflow.add_node("classify_request", classify_request)
workflow.add_node("load_budget_data", load_budget_data)
workflow.add_node("load_actual_data", load_actual_data)
workflow.add_node("calculate_variances", calculate_variances)
workflow.add_node("identify_material_variances", identify_material_variances)
workflow.add_node("analyze_drivers", analyze_drivers)
workflow.add_node("generate_commentary", generate_commentary)
workflow.add_node("compliance_check", compliance_check)
workflow.add_node("human_review", human_review)
workflow.add_node("format_output", format_output)

workflow.set_entry_point("classify_request")
workflow.add_edge("classify_request", "load_budget_data")
workflow.add_edge("load_budget_data", "load_actual_data")
workflow.add_edge("load_actual_data", "calculate_variances")
workflow.add_edge("calculate_variances", "identify_material_variances")
workflow.add_edge("identify_material_variances", "analyze_drivers")
workflow.add_edge("analyze_drivers", "generate_commentary")
workflow.add_edge("generate_commentary", "compliance_check")

workflow.add_conditional_edges(
    "compliance_check",
    should_require_approval,
    {
        "human_review": "human_review",
        "auto_approve": "format_output"
    }
)

workflow.add_edge("human_review", "format_output")
workflow.add_edge("format_output", END)

# Compile with PostgreSQL checkpointer
checkpointer = PostgresCheckpoint(connection_string=DB_URL)
app = workflow.compile(checkpointer=checkpointer)

Narrative

The LangGraph workflow implements the Evaluator-Optimizer pattern for variance analysis:

Classify Request: Intent classification to route appropriately
Load Data: Parallel loading of budget and actual data
Calculate Variances: Pure computation of differences
Identify Material: Filter using configurable thresholds
Analyze Drivers: LLM-powered root cause analysis
Generate Commentary: Natural language explanation
Compliance Check: Regulatory validation of output
Human Review: Checkpoint for approval if needed
Format Output: Final packaging for API response

PostgreSQL checkpointing enables:

Recovery from failures
Audit trail of agent decisions
Human-in-the-loop approval workflows
90-day retention for compliance

Additional C4 Diagrams

Diagram Index

ID	Level	Name	Status
C4-CTX-001	Context	System Context	✓ Complete
C4-CTX-002	Context	Multi-Tenant	✓ Complete
C4-CON-001	Container	Full Platform	✓ Complete
C4-CON-002	Container	AI Agents	✓ Complete
C4-CMP-001	Component	General Ledger	✓ Complete
C4-CMP-002	Component	Planning	✓ Complete
C4-CMP-003	Component	Reconciliation	✓ Complete
C4-CODE-001	Code	Journal Entry	✓ Complete
C4-CODE-002	Code	Variance Workflow	✓ Complete

Additional Diagrams to Create

The following diagrams should be created following the same methodology:

Context Level:

C4-CTX-003: Brazilian Market Context
C4-CTX-004: Enterprise Security Context

Container Level:

C4-CON-003: Integration Layer Detail
C4-CON-004: Compliance Service Detail
C4-CON-005: Brazilian Module (SPED, NF-e)

Component Level:

C4-CMP-004: Reporting Service Components
C4-CMP-005: Compliance Service Components
C4-CMP-006: Integration Service Components
C4-CMP-007: Auth Service Components

Code Level:

C4-CODE-003: Bank Reconciliation Algorithm
C4-CODE-004: Forecast Generation Pipeline
C4-CODE-005: SPED File Generation
C4-CODE-006: OpenFGA Policy Evaluation

Generated for CODITECT FP&A Platform Development Version: 1.0 | Date: 2026-02-03

Level 1: System Context Diagrams

C4-CTX-001: FP&A Platform System Context​

Diagram​

Narrative​

C4-CTX-002: Multi-Tenant Architecture Context​

Diagram​

Narrative​

Level 2: Container Diagrams

C4-CON-001: FP&A Platform Containers​

Diagram​

Narrative​

C4-CON-002: AI Agent Architecture Containers​

Diagram​

Narrative​

Level 3: Component Diagrams

C4-CMP-001: General Ledger Service Components​

Diagram​

Narrative​

C4-CMP-002: Planning Service Components​

Diagram​

Narrative​

C4-CMP-003: Reconciliation Service Components​

Diagram​

Narrative​

Level 4: Code Diagrams

C4-CODE-001: Journal Entry Processor Sequence​

Diagram​

Narrative​

C4-CODE-002: LangGraph Variance Analysis Workflow​

Diagram​

LangGraph Implementation​

Narrative​

Additional C4 Diagrams

Diagram Index​

Additional Diagrams to Create​

C4-CTX-001: FP&A Platform System Context

Diagram

Narrative

C4-CTX-002: Multi-Tenant Architecture Context

Diagram

Narrative

C4-CON-001: FP&A Platform Containers

Diagram

Narrative

C4-CON-002: AI Agent Architecture Containers

Diagram

Narrative

C4-CMP-001: General Ledger Service Components

Diagram

Narrative

C4-CMP-002: Planning Service Components

Diagram

Narrative

C4-CMP-003: Reconciliation Service Components

Diagram

Narrative

C4-CODE-001: Journal Entry Processor Sequence

Diagram

Narrative

C4-CODE-002: LangGraph Variance Analysis Workflow

Diagram

LangGraph Implementation

Narrative

Diagram Index

Additional Diagrams to Create