High-Level Design (HLD)

End-to-end overview of the Pixis FinOps platform: a multi-tenant SaaS that reconciles billing, ERP, and bank data on behalf of customer organizations.

flowchart TB
    subgraph users[Users]
        U[Customer org users<br/>web browser]
    end

    subgraph edge[Edge / Security]
        NX[nginx reverse proxy<br/>TLS 1.2+ termination]
        CS[CrowdSec IDS/IPS]
    end

    subgraph app[Pixis Application]
        FE[Frontend<br/>Next.js]
        BE[Backend API<br/>FastAPI]
        WK[Celery workers<br/>+ Beat scheduler]
    end

    subgraph data[Data & State]
        PG[(Managed PostgreSQL<br/>Supabase — AES-256 at rest<br/>Row-Level Security)]
        RD[(Redis<br/>task queue / cache)]
    end

    subgraph ext[External Integrations]
        ST[Stripe]
        ZO[Zoho Books]
        QB[QuickBooks]
        NS[NetSuite]
        OR[Oracle Fusion]
        GO[Google OAuth / Drive]
        AI[OpenAI / Gemini LLM]
    end

    U -->|HTTPS| NX
    NX --> CS
    NX --> FE
    NX -->|/api/v1| BE
    FE --> BE
    BE --> PG
    BE --> RD
    WK --> PG
    WK --> RD
    BE <-->|OAuth / API keys<br/>encrypted credentials| ST & ZO & QB & NS & OR
    BE <--> GO
    BE -->|document/text| AI
    WK <--> ST & ZO & QB & NS & OR

    classDef sec fill:#fde,stroke:#b36
    classDef store fill:#def,stroke:#36b
    class NX,CS sec
    class PG,RD store

Key points

• Single entry point — all traffic enters through nginx (TLS 1.2+) fronted by CrowdSec.
• Multi-tenancy — every tenant's data is isolated by PostgreSQL Row-Level Security scoped by organization_id; the frontend sends an X-Organization-Id header validated against the JWT org claim.
• Stateless app tier — frontend and backend hold no durable state; all state lives in managed PostgreSQL and Redis.
• Integrations — external ERP/billing credentials are stored encrypted (AES-256-GCM) and used by both the API (on-demand) and Celery workers (scheduled sync).
• Webhooks — Stripe and Zoho deliver events inbound to /api/v1/webhooks/... (validated by signature or shared token).