# getumbrel/umbrel-apps architecture

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

- Interactive diagram: https://gitdiagram.com/getumbrel/umbrel-apps
- Repository: https://github.com/getumbrel/umbrel-apps

## Overview

##### Main Components

a. Core Infrastructure Layer:
- Docker Engine (base)
- Docker Compose Orchestration
- App Proxy Service (authentication/routing)
- Network Management
- Volume Management

b. Application Layer:
- Individual App Containers
- App Data Volumes
- App Configuration
- Dependencies Management

c. Integration Layer:
- Bitcoin Node Integration
- Lightning Node Integration
- External Services Integration
- Inter-app Communication

##### Key Relationships to Highlight

- User → App Proxy → Individual Apps
- Apps → Persistent Storage Volumes
- Apps → Bitcoin/Lightning Node (if dependent)
- Apps → Other App Dependencies
- Apps → External Services

##### Specific Elements

a. App Container Structure:
**App Container**
- Web Service
- Configuration
- Dependencies
- Persistent Storage Mounts

b. App Proxy Details:
**App Proxy**
- Authentication
- Routing
- Whitelisting
- Blacklisting

c. Volume Management:
**Volumes**
- App Data
- Bitcoin Data
- Lightning Data

##### Implementation Details

Following flows:
- App Installation Process
- Authentication Flow
- Data Persistence
- Inter-container Communication
- External Access Points

##### Security Boundaries

Clearly mark:
- Container Isolation
- Network Segmentation
- Authentication Boundaries
- Data Access Controls

##### The dependency resolution system

Use a hierarchical layout with:
- Infrastructure at the bottom
- Applications in the middle
- User interface at the top
- Supporting services on the sides

This will create a clear visualization of how the Umbrel App Framework functions as a cohesive system while maintaining isolation and security between components.

Remember to include notes about:
- Version compatibility
- Security considerations
- Scaling capabilities
- Dependency management
- Data persistence strategies

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph User
        UI[User Interface]
    end

    subgraph "Application Layer"
        AC[App Container]
        WS[Web Service]
        CONF[Configuration]:::config
        DEP[Dependencies]
        AC --> WS
        AC --> CONF
        AC --> DEP
    end

    subgraph "Integration Layer"
        BTC[Bitcoin Node]:::btc
        LN[Lightning Node]:::ln
        CLN[Core Lightning]:::cln
        EXT[External Services]:::ext
    end

    subgraph "Core Infrastructure"
        DE[Docker Engine]
        DC[Docker Compose]:::docker
        AP[App Proxy]
        NM[Network Management]:::network
        VM[Volume Management]:::volume
    end

    subgraph "Storage Layer"
        AD[App Data]:::storage
        BD[Bitcoin Data]:::storage
        LD[Lightning Data]:::storage
        DBS[Database Storage]:::storage
        CS[Config Storage]:::storage
    end

    subgraph "Security"
        AUTH[Authentication]:::security
        WL[Whitelisting]:::security
        BL[Blacklisting]:::security
        AP --> AUTH
        AP --> WL
        AP --> BL
    end

    UI --> AP
    AP --> AC
    AC --> VM
    AC --> BTC
    AC --> LN
    AC --> CLN
    AC --> EXT
    VM --> AD
    VM --> BD
    VM --> LD
    VM --> DBS
    VM --> CS
    DE --> DC

    %% Component Mappings
    click DC "https://github.com/getumbrel/umbrel-apps/blob/master/docker-compose.yml"
    click CONF "https://github.com/getumbrel/umbrel-apps/blob/master/umbrel-app.yml"
    click VM "https://github.com/getumbrel/umbrel-apps/tree/master/data/"
    click BTC "https://github.com/getumbrel/umbrel-apps/tree/master/bitcoin/"
    click LN "https://github.com/getumbrel/umbrel-apps/tree/master/lightning/"
    click CLN "https://github.com/getumbrel/umbrel-apps/tree/master/core-lightning/"
    click AUTH "https://github.com/getumbrel/umbrel-apps/tree/master/hooks/pre-start"
    click EXT "https://github.com/getumbrel/umbrel-apps/blob/master/exports.sh"
    click NM "https://github.com/getumbrel/umbrel-apps/blob/master/torrc.template"
    click AD "https://github.com/getumbrel/umbrel-apps/tree/master/data/"
    click DBS "https://github.com/getumbrel/umbrel-apps/tree/master/data/db/"
    click CS "https://github.com/getumbrel/umbrel-apps/tree/master/data/config/"

    %% Styling
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px
    classDef docker fill:#1D63ED,color:white
    classDef security fill:#FF4444,color:white
    classDef storage fill:#FFD700,color:black
    classDef network fill:#9932CC,color:white
    classDef volume fill:#3CB371,color:white
    classDef btc fill:#F7931A,color:white
    classDef ln fill:#792EE5,color:white
    classDef cln fill:#51B13E,color:white
    classDef ext fill:#808080,color:white
    classDef config fill:#FF8C00,color:white

    %% Legend
    subgraph Legend
        L1[Docker Component]:::docker
        L2[Security Component]:::security
        L3[Storage Component]:::storage
        L4[Network Component]:::network
        L5[Volume Component]:::volume
        L6[Bitcoin Component]:::btc
        L7[Lightning Component]:::ln
        L8[Core Lightning]:::cln
        L9[External Services]:::ext
        L10[Configuration]:::config
    end
```
