Skip to content

Architecture Overview

Champa Intelligence is built on a modern, scalable architecture designed for high performance, reliability, and maintainability in enterprise Camunda 7 environments.

Architecture at a Glance

graph TB
    subgraph "Client Layer"
        A[Web Browser]
        B[Alpine.js]
        C[Tailwind CSS]
        D[BPMN.js/DMN.js]
    end

    subgraph "Application Layer"
        E[Gunicorn WSGI]
        F[Flask Application]
        G[Blueprint Architecture]
    end

    subgraph "Data Layer"
        H[Redis Cache]
        I[(Camunda DB)]
        J[(System DB)]
    end

    subgraph "External Services"
        K[Google Gemini AI]
        L[Camunda REST API]
        M[Prometheus/Grafana]
    end

    A --> B
    B --> E
    E --> F
    F --> G
    F --> H
    F --> I
    F --> J
    F --> K
    F --> L
    F --> M
Hold "Alt" / "Option" to enable pan & zoom

Architectural Principles

1. Performance First

Multi-Level Caching - Redis for hot data (sessions, query results) - PostgreSQL fallback for session management - Smart cache invalidation on deployments - Different TTLs for static vs. dynamic data

Lazy Loading - Dashboard components load on-demand - Reduces initial page load to <500ms - Parallel data fetching with ThreadPoolExecutor - Progressive enhancement

Optimized Queries - 80+ hand-crafted SQL queries - Strategic indexes and query planning - Batch operations for bulk data - Connection pooling

2. Separation of Concerns

Blueprint Architecture - Each feature is a self-contained Flask Blueprint - Clean separation between auth, analytics, monitoring - Independent testing and deployment per blueprint - Modular and maintainable codebase

Database Separation - Camunda DB: Read-only access to process data - System DB: Champa's own data (users, sessions, cache) - No schema pollution in customer database - Independent scaling

3. Scalability

Horizontal Scaling - Stateless application design - Session data in Redis (shared across instances) - Multiple Gunicorn workers per container - Load balancer ready

Vertical Scaling - Configurable worker/thread count - Connection pooling for databases - Efficient memory management - Resource limits per container

4. Security by Design

Defense in Depth - JWT-based authentication - Role-based access control (RBAC) - Audit logging for all actions - SQL injection prevention (parameterized queries)

Data Protection - Salted password hashing (PBKDF2) - Secure session management - API token lifecycle management - HTTPS enforcement

Technology Stack

Backend

Component Technology Purpose
Language Python 3.12 Core application logic
Framework Flask 3.x Web framework
WSGI Server Gunicorn Production application server
Database Driver psycopg2 PostgreSQL connectivity
Cache Client redis High-performance caching
AI SDK google-genai Gemini API (default)
HTTP Client requests External API calls
XML Parser lxml BPMN/DMN parsing
Auth PyJWT Token-based authentication

Frontend

Component Technology Purpose
JavaScript Framework Alpine.js 3.x Reactive UI components
CSS Framework Tailwind CSS 3.x Utility-first styling
BPMN Rendering bpmn-js 18.x Process diagram visualization
DMN Rendering dmn-js 17.x Decision table visualization
Charts Chart.js 4.x Data visualization
Build Tool Webpack 5.x Module bundling
Transpiler Babel ES6+ to ES5

Infrastructure

Component Technology Purpose
Container Docker Application containerization
Orchestration Docker Compose Multi-container deployment
Database PostgreSQL 15+ Data persistence
Cache Redis 7+ In-memory data store
Web Server Nginx (optional) Reverse proxy, static files
Monitoring Prometheus + Grafana Metrics and dashboards

Data Flow Architecture

Request Flow

sequenceDiagram
    participant Browser
    participant Flask
    participant Redis
    participant SystemDB
    participant CamundaDB

    Browser->>Flask: HTTP Request + JWT
    Flask->>Redis: Validate Session
    Redis-->>Flask: Session Data
    Flask->>Flask: Check Permission

    alt Cache Hit
        Flask->>Redis: Get Cached Data
        Redis-->>Flask: Return Data
    else Cache Miss
        Flask->>CamundaDB: Query Data
        CamundaDB-->>Flask: Result
        Flask->>Redis: Store in Cache
    end

    Flask-->>Browser: JSON Response
Hold "Alt" / "Option" to enable pan & zoom

Authentication Flow

sequenceDiagram
    participant User
    participant Flask
    participant Redis
    participant SystemDB

    User->>Flask: POST /auth/login
    Flask->>SystemDB: Verify Credentials
    SystemDB-->>Flask: User Data
    Flask->>Flask: Generate JWT
    Flask->>Redis: Store Session
    Flask-->>User: JWT Token + Cookie

    User->>Flask: GET /dashboard (with JWT)
    Flask->>Redis: Validate Session
    Redis-->>Flask: Session Valid
    Flask->>Flask: Check Permission
    Flask-->>User: Dashboard HTML
Hold "Alt" / "Option" to enable pan & zoom

Detailed Architecture Sections

Explore each architectural aspect in detail:

System Design

Comprehensive architecture documentation with diagrams, component descriptions, and design patterns.

Database Schema

Complete schema documentation for both Camunda and System databases, including relationships and indexes.

Caching Strategy

Multi-level caching architecture, TTL configuration, and invalidation strategies.

Security Model

Authentication, authorization, RBAC, audit logging, and security best practices.

Frontend Architecture

Client-side architecture, Alpine.js patterns, lazy loading implementation, and build process.

Performance Optimization

Query optimization, caching strategies, connection pooling, and scaling approaches.

Monitoring & Observability

Application Logs

Log Categories: 

logs/
├── application.log    # General application
├── access.log         # HTTP requests
├── security.log       # Auth & security events
├── database.log       # DB queries & performance
├── cache.log          # Cache operations
├── ai.log            # AI analysis operations
└── structured.log     # Machine-readable JSON

Prometheus Metrics

Exported Metrics: - Cluster health (nodes, instances, incidents) - Per-node metrics (workload, job rates) - JVM metrics (heap, GC, threads) - Database metrics (connections, latency) - Process-level KPIs (health scores, rates)

Health Checks

GET /health/ping          # Simple liveness
GET /health/db            # Database connectivity
GET /health/api/full      # Comprehensive health
GET /health/light/metrics # Prometheus metrics

Next Steps