# actualbudget/actual-server architecture

> Architecture diagram of the GitHub repository actualbudget/actual-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/actualbudget/actual-server
- Repository: https://github.com/actualbudget/actual-server

## Overview

##### Main System Components

a) Core Application Layer:
- Entry point (app.js)
- Account Management System (src/accounts/*)
- Authentication Systems (password.js and openid.js)
- Database Layer (src/db.js, src/account-db.js)
- Migration System (migrations/*)

b) Integration Services:
- GoCardless Banking Integration (src/app-gocardless/*)
- SimpleFin Integration (src/app-simplefin/*)
- Sync Service (src/app-sync/*)

c) Security Layer:
- Secrets Management (src/app-secrets.js)
- User Service (src/services/user-service.js)

##### Architectural Patterns to Highlight

- Local-First Architecture: Show the local storage and sync mechanisms
- Multi-User Support: Illustrate user isolation and management
- Banking Integration Framework: Display the pluggable bank adapter system
- Migration System: Show the database evolution path

##### Component Relationships

**[Client Applications] ←→ [Sync Service]**
- ↕
- [Core Server Layer]
- ↕
- [Banking APIs] ←→ [Integration Layer]
- ↕
- [Database Layer]

##### Specific Implementation Details

- Blue rectangles: Core services
- Green diamonds: External integrations
- Red hexagons: Security components
- Purple clouds: Third-party services

##### Key Flows to Illustrate

a) Authentication Flow:
**User → OpenID/Password Auth → Token Generation → Protected Resources**

b) Banking Integration Flow:
**Bank API → GoCardless Adapter → Bank Factory → Core Services**

c) Sync Flow:
**Client → Sync Service → File Service → Database**

##### Technical Stack Indicators

Technologies used:
- Node.js runtime
- SQL database
- REST APIs
- OpenID Connect
- Docker containerization

Remember to:
- Use clear, consistent naming
- Data flow directions
- Async operations
- Security boundaries
- Version/migration paths
- Scaling points

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        CL[Client Applications]:::client
    end

    subgraph "Core Application Layer"
        EP["Entry Point"]:::core
        click EP "https://github.com/actualbudget/actual-server/blob/master/app.js"
        
        subgraph "Authentication"
            OID["OpenID Auth"]:::security
            click OID "https://github.com/actualbudget/actual-server/blob/master/src/accounts/openid.js"
            PWD["Password Auth"]:::security
            click PWD "https://github.com/actualbudget/actual-server/blob/master/src/accounts/password.js"
        end
        
        subgraph "Account Management"
            AMS["Account System"]:::core
            click AMS "https://github.com/actualbudget/actual-server/tree/master/src/accounts/"
        end
    end

    subgraph "Integration Layer"
        GC["GoCardless Integration"]:::integration
        click GC "https://github.com/actualbudget/actual-server/tree/master/src/app-gocardless/"
        SF["SimpleFin Integration"]:::integration
        click SF "https://github.com/actualbudget/actual-server/tree/master/src/app-simplefin/"
        BF["Bank Factory"]:::integration
        click BF "https://github.com/actualbudget/actual-server/blob/master/src/app-gocardless/bank-factory.js"
        BI["Bank Implementations"]:::integration
        click BI "https://github.com/actualbudget/actual-server/tree/master/src/app-gocardless/banks/"
    end

    subgraph "Sync Layer"
        SS["Sync Service"]:::sync
        click SS "https://github.com/actualbudget/actual-server/tree/master/src/app-sync/"
        FS["Files Service"]:::sync
        click FS "https://github.com/actualbudget/actual-server/blob/master/src/app-sync/services/files-service.js"
        VL["Validation Layer"]:::sync
        click VL "https://github.com/actualbudget/actual-server/blob/master/src/app-sync/validation.js"
    end

    subgraph "Security Layer"
        SM["Secrets Management"]:::security
        click SM "https://github.com/actualbudget/actual-server/blob/master/src/services/secrets-service.js"
        US["User Service"]:::security
        click US "https://github.com/actualbudget/actual-server/blob/master/src/services/user-service.js"
    end

    subgraph "Data Layer"
        DB[("Main Database")]:::database
        click DB "https://github.com/actualbudget/actual-server/blob/master/src/db.js"
        ADB[("Account Database")]:::database
        click ADB "https://github.com/actualbudget/actual-server/blob/master/src/account-db.js"
        MIG["Migration System"]:::database
        click MIG "https://github.com/actualbudget/actual-server/tree/master/migrations/"
    end

    subgraph "External Services"
        BA[("Banking APIs")]:::external
        TPS[("Third Party Services")]:::external
    end

    %% Connections
    CL <--> SS
    SS --> FS
    FS --> DB
    EP --> AMS
    AMS --> DB
    OID & PWD --> AMS
    GC & SF --> BF
    BF --> BI
    BI --> BA
    SS --> VL
    SM --> US
    US --> ADB
    DB --> MIG
    ADB --> MIG

    %% Styles
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef security fill:#F44336,stroke:#C62828,color:white
    classDef integration fill:#4CAF50,stroke:#2E7D32,color:white
    classDef database fill:#FFC107,stroke:#FFA000,color:black
    classDef external fill:#9C27B0,stroke:#6A1B9A,color:white
    classDef sync fill:#00BCD4,stroke:#00838F,color:white
    classDef client fill:#795548,stroke:#4E342E,color:white

    %% Legend
    subgraph Legend
        L1[Core Services]:::core
        L2[Security Components]:::security
        L3[Integration Services]:::integration
        L4[("Data Stores")]:::database
        L5[("External Services")]:::external
        L6[Sync Components]:::sync
        L7[Client Layer]:::client
    end
```
