# trailbaseio/trailbase architecture

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

- Interactive diagram: https://gitdiagram.com/trailbaseio/trailbase
- Repository: https://github.com/trailbaseio/trailbase

## Overview

##### Main Components

a. Core Server Components:
- TrailBase Core (trailbase-core/)
- Authentication System
- Admin Interface
- Record Management
- JS/TS Runtime (V8 Engine)
- SQLite Database Integration
- Schema Management

b. Client Libraries:
- TypeScript/JavaScript Client
- Dart/Flutter Client
- .NET Client
- Python Client

c. Extension System:
- Custom Extensions (trailbase-extension/)
- SQLite Extensions (trailbase-sqlite/)

**┌─ Client Layer ─────────────────────────────────────┐**
- TypeScript │ Dart/Flutter │ .NET │ Python │ Others │
- ┬───────────────────────────────┘

**┌─ API Layer ─────────▼───────────────────────────────┐**
- Record APIs │ Admin APIs │ Auth APIs │ Custom APIs   │
- ┬───────────────────────────────┘

**┌─ Core Services ─────▼───────────────────────────────┐**
- Auth Service │ JS Runtime │ Schema Manager │ Admin UI│
- ┬───────────────────────────────┘

**┌─ Storage Layer ─────▼───────────────────────────────┐**
- SQLite + Extensions │ File Storage               │
- ┘

##### Key Interactions to Highlight

- Bidirectional communication between clients and API layer
- How the JS Runtime integrates with core services
- Demonstrate authentication flow through the system
- Data flow between core services and storage layer
- Extension points in the system

##### Implementation Details

- SQLite as the primary database
- V8 for JavaScript/TypeScript runtime
- Built-in authentication system
- Admin UI interface
- File storage system
- Extension system

##### Additional Elements

- Version compatibility information
- Scaling capabilities
- Backup/recovery paths
- Monitoring/logging points

- Single-file deployment
- Built-in type-safe APIs
- Integrated auth system
- Sub-millisecond latency
- No need for separate caching layer

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph Clients
        TS["TypeScript Client"]
        Dart["Dart/Flutter Client"]
        NET[".NET Client"]
        Python["Python Client"]
        Others["Other Clients"]
    end
    
    %% API Layer
    subgraph APIs
        RecordAPI["Record APIs"]:::api
        AdminAPI["Admin APIs"]:::api
        AuthAPI["Auth APIs"]:::api
        CustomAPI["Custom APIs"]:::api
    end
    
    %% Core Services
    subgraph Core
        AuthService["Authentication Service"]:::core
        JSRuntime["JS/TS Runtime (V8)"]:::core
        SchemaManager["Schema Manager"]:::core
        AdminUI["Admin Interface"]:::core
        CoreServer["TrailBase Core"]:::core
    end
    
    %% Storage Layer
    subgraph Storage
        SQLite[(SQLite DB)]:::storage
        FileStorage["File Storage"]:::storage
        SQLiteExt["SQLite Extensions"]:::storage
    end
    
    %% Extensions
    subgraph Extensions
        CustomExt["Custom Extensions"]:::extension
    end
    
    %% Connections
    Clients --> APIs
    APIs --> Core
    Core --> Storage
    Core --> Extensions
    Extensions --> Storage
    
    %% Detailed Connections
    AuthService --> SQLite
    JSRuntime --> SQLite
    SchemaManager --> SQLite
    AdminUI --> CoreServer
    CoreServer --> SQLite
    CustomExt --> SQLiteExt
    
    %% Styling
    classDef api fill:#FFD700,stroke:#000
    classDef core fill:#4169E1,stroke:#000,color:#fff
    classDef storage fill:#FFA500,stroke:#000
    classDef extension fill:#800080,stroke:#000,color:#fff
    
    %% Click Events
    click TS "https://github.com/trailbaseio/trailbase/tree/main/client/trailbase-ts/"
    click Dart "https://github.com/trailbaseio/trailbase/tree/main/client/trailbase-dart/"
    click NET "https://github.com/trailbaseio/trailbase/tree/main/client/trailbase-dotnet/"
    click Python "https://github.com/trailbaseio/trailbase/tree/main/client/trailbase-py/"
    click AuthService "https://github.com/trailbaseio/trailbase/tree/main/trailbase-core/src/auth/"
    click AdminAPI "https://github.com/trailbaseio/trailbase/tree/main/trailbase-core/src/admin/"
    click AuthAPI "https://github.com/trailbaseio/trailbase/tree/main/trailbase-core/src/auth/api/"
    click JSRuntime "https://github.com/trailbaseio/trailbase/blob/main/trailbase-core/src/js/runtime.rs"
    click SchemaManager "https://github.com/trailbaseio/trailbase/blob/main/trailbase-core/src/schema.rs"
    click AdminUI "https://github.com/trailbaseio/trailbase/tree/main/trailbase-core/js/admin/"
    click CoreServer "https://github.com/trailbaseio/trailbase/tree/main/trailbase-core/src/"
    click CustomExt "https://github.com/trailbaseio/trailbase/tree/main/trailbase-extension/"
    click SQLiteExt "https://github.com/trailbaseio/trailbase/tree/main/trailbase-sqlite/"
    click SQLite "https://github.com/trailbaseio/trailbase/tree/main/trailbase-sqlite/src/"
    
    %% Legend
    subgraph Legend
        L1["API"]:::api
        L2["Core Service"]:::core
        L3["Storage"]:::storage
        L4["Extension"]:::extension
    end
```
