# tale/headplane architecture

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

- Interactive diagram: https://gitdiagram.com/tale/headplane
- Repository: https://github.com/tale/headplane

## Overview

##### Main Components Identification

The system should be represented with these key components:

a) Frontend Layer:
- React-based UI (indicated by .tsx files in /app)
- Component structure (/app/components)
- Route-based architecture (/app/routes)
- Tailwind CSS styling (tailwind.config.ts)

b) Integration Layer:
- Docker integration
- Kubernetes integration
- Process management
- Configuration management

c) Backend Services:
- Authentication system (OIDC support)
- Headscale server integration
- Session management
- Health monitoring

##### Component Relationships

**[Client Browser] → [Frontend Layer] → [Integration Layer] → [Headscale Server]**
- ↓
- [Authentication Services]

##### Detailed Component Breakdown

Frontend Layer (Blue Components):
- ACLs Management
- DNS Management
- Machine Management
- User Management
- Settings Management

Integration Layer (Green Components):
- Integration options:
- Docker Container
- Kubernetes Pod
- Native Process

Backend Services (Yellow Components):
- Authentication Flow
- Session Management
- Health Checks
- Configuration Management

##### Data Flow Indicators

- User authentication flow
- API requests to Headscale
- Configuration updates
- Health check status

##### Technical Details

Annotations for:
- TypeScript types (/app/types)
- Integration methods
- Configuration options
- Health check endpoints

##### Deployment Options

Two deployment scenarios:
- Basic Deployment
- Advanced Deployment (with full integration)

Styling Guidelines:

Level of Detail:
- Keep high-level architecture visible
- Integration points clearly
- Maintain clarity of data flow

Remember to highlight the security aspects, particularly around authentication and ACL management, as these are critical for a network management interface.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        Browser["Web Browser"]
    end

    subgraph FrontendLayer["Frontend Layer"]
        direction TB
        Root["Root Component"]:::frontend
        Layout["Dashboard Layout"]:::frontend
        Components["Components"]:::frontend
        Routes["Routes"]:::frontend
        Styles["Styling System"]:::frontend
    end

    subgraph FeatureModules["Feature Modules"]
        direction TB
        ACLs["ACLs Management"]:::feature
        DNS["DNS Management"]:::feature
        Machines["Machine Management"]:::feature
        Users["User Management"]:::feature
        Settings["Settings Management"]:::feature
    end

    subgraph IntegrationLayer["Integration Layer"]
        direction TB
        Docker["Docker Integration"]:::integration
        K8s["Kubernetes Integration"]:::integration
        Process["Process Management"]:::integration
    end

    subgraph BackendServices["Backend Services"]
        direction TB
        Auth["Authentication System"]:::backend
        Session["Session Management"]:::backend
        Health["Health Monitoring"]:::backend
        Config["Configuration Management"]:::backend
    end

    subgraph Types["Type Definitions"]
        direction TB
        MachineTypes["Machine Types"]:::type
        UserTypes["User Types"]:::type
        RouteTypes["Route Types"]:::type
        KeyTypes["Key Types"]:::type
    end

    Browser --> Root
    Root --> Layout
    Layout --> Components
    Layout --> Routes

    Routes --> FeatureModules
    Routes --> BackendServices

    IntegrationLayer --> HeadscaleServer["Headscale Server"]:::external

    %% Component relationships
    Components --> ACLs
    Components --> DNS
    Components --> Machines
    Components --> Users
    Components --> Settings

    %% Backend relationships
    Auth --> Session
    Config --> IntegrationLayer
    Health --> HeadscaleServer

    %% Type relationships
    Types --> Components
    Types --> Routes

    %% Styling
    classDef frontend fill:#3b82f6,color:#fff
    classDef feature fill:#10b981,color:#fff
    classDef integration fill:#6366f1,color:#fff
    classDef backend fill:#f59e0b,color:#fff
    classDef type fill:#8b5cf6,color:#fff
    classDef external fill:#ef4444,color:#fff

    %% Click events
    click Components "https://github.com/tale/headplane/tree/main/app/components"
    click Routes "https://github.com/tale/headplane/tree/main/app/routes"
    click Styles "https://github.com/tale/headplane/blob/main/app/tailwind.css"
    click Docker "https://github.com/tale/headplane/blob/main/app/integration/docker.ts"
    click K8s "https://github.com/tale/headplane/blob/main/app/integration/kubernetes.ts"
    click Process "https://github.com/tale/headplane/blob/main/app/integration/proc.ts"
    click Auth "https://github.com/tale/headplane/tree/main/app/routes/auth"
    click Session "https://github.com/tale/headplane/blob/main/app/utils/sessions.ts"
    click Health "https://github.com/tale/headplane/blob/main/app/routes/util/healthz.ts"
    click Config "https://github.com/tale/headplane/blob/main/app/utils/config/headplane.ts"
    click ACLs "https://github.com/tale/headplane/tree/main/app/routes/acls"
    click DNS "https://github.com/tale/headplane/tree/main/app/routes/dns"
    click Machines "https://github.com/tale/headplane/tree/main/app/routes/machines"
    click Users "https://github.com/tale/headplane/tree/main/app/routes/users"
    click Settings "https://github.com/tale/headplane/tree/main/app/routes/settings"
    click MachineTypes "https://github.com/tale/headplane/blob/main/app/types/Machine.ts"
    click UserTypes "https://github.com/tale/headplane/blob/main/app/types/User.ts"
    click RouteTypes "https://github.com/tale/headplane/blob/main/app/types/Route.ts"
    click KeyTypes "https://github.com/tale/headplane/blob/main/app/types/Key.ts"
    click Layout "https://github.com/tale/headplane/blob/main/app/layouts/dashboard.tsx"
    click Root "https://github.com/tale/headplane/blob/main/app/root.tsx"
```
