# claceio/clace architecture

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

- Interactive diagram: https://gitdiagram.com/claceio/clace
- Repository: https://github.com/claceio/clace

## Overview

##### Main Components

a. Core Server Components:
- HTTP/HTTPS Server (ports 25222/25223)
- Authentication System (OAuth/SSO)
- Router & Request Handler
- App Manager
- Container Manager
- Plugin System
- Metadata Store (SQLite)

b. Application Components:
- App Runtime Environment
- Static File Server
- Template Engine
- Security Sandbox
- Virtual Filesystem
- Store System (SQLite-based)

c. Development Tools:
- TailwindCSS Integration
- DaisyUI Integration
- esbuild Module Generator
- Development Mode Handler

##### Component Relationships

- External requests → HTTP Server → Router → App Handler → App Runtime
- App Runtime ↔ Plugin System
- App Runtime ↔ Container Manager (for containerized apps)
- App Runtime ↔ Virtual Filesystem ↔ SQLite Storage
- Development Tools → Static Assets → Virtual Filesystem

##### Specific Implementation Details

**[External Clients] → [HTTPS Server (25223)]**
- [HTTP Server (25222)]
- ↓
**[Authentication Layer (OAuth/SSO)] → [Router]**
- ↓
- [App Manager & Handler]
- ↓
- ┌─────────┴──────────────┐
- ↓                        ↓
- [App Runtime Environment]    [Container Manager]
- ↓                        ↓
- [Plugin System]           [Docker/Podman]
- ↓
- ┌─────┴────┬────────┐
- [Store API] [Templates] [Static Files]
- ↓          ↓           ↓
**[SQLite DB]  [HTML/CSS]  [Virtual FS]**

##### Key Architectural Patterns to Highlight

- Plugin-based Architecture: Show how the plugin system enables extensibility
- Security Model: Illustrate the sandboxed execution environment
- GitOps Workflow: Show the deployment flow from Git repositories
- Virtual Filesystem: Demonstrate content-hash based file serving
- Container Integration: Show how containerized apps are managed

##### Important Notes

- Version numbers for major components
- Security boundaries clearly
- Async vs sync operations
- Optional components (like container support)
- Configuration paths
- Monitoring/logging points

##### Technical Details

- Go-based implementation
- SQLite as the current storage backend
- Support for both HTTP and HTTPS
- Integration with external services (Docker/Podman)
- Authentication providers
- Static file optimization (Brotli compression)

This architecture reflects Clace's nature as a sophisticated web application platform that can handle both traditional and containerized applications while maintaining security and performance.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph External
        Client([External Clients])
    end

    subgraph ServerLayer[Server Layer]
        HTTPS[HTTPS Server :25223]:::server
        HTTP[HTTP Server :25222]:::server
        Auth[Authentication System]:::security
        Router[Router & Request Handler]:::server
    end

    subgraph AppLayer[Application Layer]
        AppMgr[App Manager]:::app
        AppRuntime[App Runtime Environment]:::app
        ContainerMgr[Container Manager]:::container
        PluginSys[Plugin System]:::plugin
    end

    subgraph ExecutionLayer[Execution Layer]
        Security[Security Sandbox]:::security
        Templates[Template Engine]:::core
        StaticFiles[Static File Server]:::core
        VFS[Virtual Filesystem]:::storage
    end

    subgraph StorageLayer[Storage Layer]
        MetaStore[(Metadata Store)]:::storage
        StoreSystem[(Store System)]:::storage
    end

    subgraph DevTools[Development Tools]
        TailwindCSS[TailwindCSS]:::dev
        DaisyUI[DaisyUI]:::dev
        ESBuild[esbuild]:::dev
        DevMode[Dev Mode Handler]:::dev
    end

    %% Relationships
    Client --> HTTPS & HTTP
    HTTPS & HTTP --> Auth
    Auth --> Router
    Router --> AppMgr
    AppMgr --> AppRuntime
    AppRuntime --> ContainerMgr
    AppRuntime --> PluginSys
    AppRuntime --> Security
    Security --> Templates
    Security --> StaticFiles
    Security --> VFS
    VFS --> MetaStore
    AppRuntime --> StoreSystem
    DevTools --> StaticFiles

    %% Click Events
    click HTTP "https://github.com/claceio/clace/blob/main/internal/system/http.go"
    click Auth "https://github.com/claceio/clace/blob/main/internal/server/auth.go"
    click Router "https://github.com/claceio/clace/blob/main/internal/server/router.go"
    click ContainerMgr "https://github.com/claceio/clace/blob/main/internal/app/container_manager.go"
    click PluginSys "https://github.com/claceio/clace/blob/main/internal/plugin/plugin.go"
    click MetaStore "https://github.com/claceio/clace/tree/main/internal/metadata/"
    click AppRuntime "https://github.com/claceio/clace/blob/main/internal/app/app.go"
    click VFS "https://github.com/claceio/clace/tree/main/internal/app/appfs/"
    click StoreSystem "https://github.com/claceio/clace/tree/main/internal/app/store/"
    click Templates "https://github.com/claceio/clace/tree/main/internal/app/action/"
    click DevMode "https://github.com/claceio/clace/tree/main/internal/app/dev/"
    click Security "https://github.com/claceio/clace/tree/main/internal/passwd/"

    %% Styling
    classDef server fill:#2374ab
    classDef security fill:#7209b7
    classDef app fill:#4ecdc4
    classDef container fill:#ffe66d
    classDef plugin fill:#ff6b6b
    classDef core fill:#95d5b2
    classDef storage fill:#40916c
    classDef dev fill:#f77f00

    %% Legend
    subgraph Legend
        ServerComp[Server Components]:::server
        SecurityComp[Security Components]:::security
        AppComp[App Components]:::app
        ContainerComp[Container Components]:::container
        PluginComp[Plugin Components]:::plugin
        CoreComp[Core Components]:::core
        StorageComp[Storage Components]:::storage
        DevComp[Development Components]:::dev
    end
```
