# uselotus/lotus architecture

> Architecture diagram of the GitHub repository uselotus/lotus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uselotus/lotus
- Repository: https://github.com/uselotus/lotus

## Overview

##### High-Level Architecture Components

a) Frontend Layer:
- React TypeScript application (in /frontend)
- User interface for plan management, metrics, and experimentation

b) Backend Services:
- Main Django Backend (/backend)
- Go Microservices:
- Event Ingestion Service (/go/event-ingestion)
- Event Guidance Service (/go/event-guidance)

c) Data Storage:
- PostgreSQL with TimescaleDB
- Redis for caching
- Redpanda (Kafka-compatible messaging)

d) Background Processing:
- Celery workers for async tasks

##### Component Relationships

a) Client Interaction Flow:
**External Clients -> Nginx Proxy -> Frontend/Backend Services**

b) Event Processing Flow:
**Events -> Event Ingestion (Go) -> Redpanda -> Event Consumer -> PostgreSQL**

c) Data Flow:
**Django Backend <-> Redis Cache**
**Django Backend <-> PostgreSQL**
**Django Backend <-> Celery Workers**

##### Specific Architectural Elements

Key subsystems:

a) Authentication/Authorization:
- API token validation flow
- Organization/Team management

b) Billing Components:
- Metering system
- Invoice generation
- Payment processor integrations

c) Event Processing:
- Event ingestion pipeline
- Real-time processing
- Historical aggregation

##### Integration Points

External integration capabilities:
- Payment processors (Stripe, Braintree)
- CRM systems (Salesforce)
- Accounting systems (NetSuite)
- Analytics platforms

##### Detailed Component Breakdown

For the Django backend, show:
- API endpoints (/backend/api)
- Billing logic (/backend/metering_billing)
- Authentication services (/backend/metering_billing/auth)
- Background tasks (/backend/metering_billing/tasks.py)

##### Scalability of individual components

This architecture should reflect Lotus's capability to handle complex pricing models, subscription management, and experimentation while maintaining flexibility for integration with existing stacks.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Define styles
    classDef frontend fill:#3498db,color:white
    classDef backend fill:#2ecc71,color:white
    classDef database fill:#e74c3c,color:white
    classDef cache fill:#f1c40f,color:white
    classDef queue fill:#9b59b6,color:white
    classDef service fill:#1abc9c,color:white
    classDef external fill:#95a5a6,color:white

    %% External Clients
    Client[Client Applications]:::external

    %% Frontend Layer
    subgraph Frontend
        UI["React TypeScript UI"]:::frontend
        IntegrationUI["Integration Components"]:::frontend
    end

    %% Backend Services
    subgraph BackendServices
        DjangoCore["Django Core"]:::backend
        AuthService["Auth Service"]:::backend
        APILayer["API Layer"]:::backend
        BillingEngine["Billing Engine"]:::backend
        WebhookHandler["Webhook Handler"]:::backend
    end

    %% Event Processing
    subgraph EventProcessing
        EventIngestion["Event Ingestion Service"]:::service
        EventGuidance["Event Guidance Service"]:::service
        EventAggregation["Event Aggregation"]:::service
    end

    %% Background Processing
    subgraph BackgroundJobs
        CeleryWorkers["Celery Workers"]:::service
    end

    %% Data Storage
    subgraph DataStorage
        PostgreSQL[(PostgreSQL/TimescaleDB)]:::database
        Redis[(Redis Cache)]:::cache
        Redpanda[("Redpanda Queue")]:::queue
    end

    %% External Integrations
    subgraph ExternalServices
        PaymentProcessors["Payment Processors"]:::external
        CRM["CRM Systems"]:::external
        Accounting["Accounting Systems"]:::external
        Analytics["Analytics Platforms"]:::external
    end

    %% Connections
    Client --> UI
    UI --> APILayer
    IntegrationUI --> APILayer
    
    APILayer --> DjangoCore
    APILayer --> AuthService
    DjangoCore --> BillingEngine
    DjangoCore --> WebhookHandler
    
    EventIngestion --> Redpanda
    Redpanda --> EventGuidance
    EventGuidance --> EventAggregation
    EventAggregation --> PostgreSQL
    
    DjangoCore --> Redis
    DjangoCore --> PostgreSQL
    DjangoCore --> CeleryWorkers
    CeleryWorkers --> PostgreSQL
    
    BillingEngine --> PaymentProcessors
    WebhookHandler --> ExternalServices
    
    %% Click Events
    click UI "https://github.com/uselotus/lotus/tree/main/frontend/src/components/"
    click IntegrationUI "https://github.com/uselotus/lotus/tree/main/frontend/src/integrations/"
    click DjangoCore "https://github.com/uselotus/lotus/blob/main/backend/lotus/settings.py"
    click AuthService "https://github.com/uselotus/lotus/tree/main/backend/metering_billing/auth/"
    click APILayer "https://github.com/uselotus/lotus/blob/main/backend/api/views.py"
    click BillingEngine "https://github.com/uselotus/lotus/blob/main/backend/metering_billing/invoice.py"
    click WebhookHandler "https://github.com/uselotus/lotus/blob/main/backend/metering_billing/webhooks.py"
    click EventIngestion "https://github.com/uselotus/lotus/tree/main/go/event-ingestion/"
    click EventGuidance "https://github.com/uselotus/lotus/tree/main/go/event-guidance/"
    click EventAggregation "https://github.com/uselotus/lotus/tree/main/backend/metering_billing/aggregation/"
    click CeleryWorkers "https://github.com/uselotus/lotus/blob/main/backend/lotus/lotus_celery.py"

    %% Legend
    subgraph Legend
        Frontend_L["Frontend"]:::frontend
        Backend_L["Backend"]:::backend
        Database_L["Database"]:::database
        Cache_L["Cache"]:::cache
        Queue_L["Queue"]:::queue
        Service_L["Service"]:::service
        External_L["External"]:::external
    end
```
