​

Architecture

​

Overview

┌─────────────────────────────────────────────────────────┐
│                    TrailBase Server                     │
├─────────────────────────────────────────────────────────┤
│  Admin UI (Embedded)    │    REST APIs (Axum Router)   │
├─────────────────────────────────────────────────────────┤
│  AppState (Shared State & Configuration)               │
├───────────────┬─────────────────┬──────────────────────┤
│  Auth System  │  Record APIs    │  WASM Runtime        │
├───────────────┴─────────────────┴──────────────────────┤
│  Connection Manager (SQLite Pool)                       │
├─────────────────────────────────────────────────────────┤
│  SQLite Database + Extensions                           │
└─────────────────────────────────────────────────────────┘

​

Core Components

​

Server Layer

1. Configuration Loading: Reads config from traildepot/config.textproto
2. Database Initialization: Sets up SQLite with extensions and migrations
3. Router Setup: Configures routes for APIs, admin UI, and custom endpoints
4. Runtime Initialization: Prepares WASM runtime for custom handlers

// Defined in server/mod.rs:97-106
pub struct Server {
  pub state: AppState,
  pub main_router: (String, Router),
  pub admin_router: Option<(String, Router)>,
  pub tls: Option<(CertificateDer<'static>, PrivateKeyDer<'static>)>,
}

​

Application State

• Data Directory: File system paths for data, uploads, and configuration
• Database Connections: Connection manager with pooling and caching
• Authentication: JWT helper, auth options, and OAuth configuration
• Record APIs: Configured table/view APIs with access control
• Job Registry: Scheduled tasks and background jobs
• WASM Runtimes: WebAssembly execution environments
• Object Store: File upload storage (local or S3)
• Mailer: Email sending configuration

// Key AppState methods from app_state.rs:199-311
pub fn data_dir(&self) -> &DataDir
pub fn connection_manager(&self) -> ConnectionManager
pub fn lookup_record_api(&self, name: &str) -> Option<RecordApi>
pub fn auth_options(&self) -> Arc<AuthOptions>
pub fn jwt(&self) -> &JwtHelper

​

SQLite Core

• Connection Pooling: Manages multiple connections for different database combinations
• Read/Write Separation: Optimizes concurrency with dedicated read threads
• Metadata Caching: Schema information cached per connection
• Attached Databases: Support for multiple SQLite databases in a single connection

// From connection.rs:84-82
pub struct ConnectionManager {
  state: Arc<ConnectionManagerState>,
}

// Key capabilities:
- main_entry() -> ConnectionEntry  // Primary database connection
- get_entry(...) -> ConnectionEntry  // Get/create cached connections
- rebuild_metadata() -> Result<(), ConnectionError>  // Refresh schema cache

• Extensions: JSON functions, full-text search, WASM functions
• Migrations: Automatic schema migrations using Refinery
• Triggers: File deletion triggers for blob cleanup
• Pragmas: Optimized settings (WAL mode, synchronous, mmap_size)

​

WASM Runtime

// From wasm/mod.rs:19
pub(crate) use trailbase_wasm_runtime_host::{
  HttpStore,    // HTTP request handling
  KvStore,      // Key-value storage
  Runtime,      // WASM execution environment
  SharedState,  // Shared state between instances
};

1. HTTP Handlers: Custom API endpoints written in WASM
2. Job Handlers: Scheduled background tasks
3. SQLite Functions: Custom SQL functions implemented in WASM
4. File System Access: Sandboxed FS access for WASM components

// WASM runtime initialization from wasm/mod.rs:71-116
pub(crate) fn wasm_runtimes_builder(
  data_dir: DataDir,
  conn: Connection,
  rt: Option<tokio::runtime::Handle>,
  runtime_root_fs: Option<PathBuf>,
  shared_kv_store: Option<KvStore>,
  dev: bool,
) -> Result<WasmRuntimeBuilder, AnyError>

​

Admin UI

• Schema management (tables, indexes, views)
• User administration
• Record API configuration
• System logs and monitoring
• OAuth provider setup

​

Data Flow

​

Request Lifecycle

1. HTTP Request → Axum Router
2. Middleware: Logging, CORS, Cookies, Rate Limiting
3. Authentication: JWT validation (if required)
4. Record API: Access control checks (ACL + Rules)
5. SQLite: Query execution
6. Response: JSON serialization
7. HTTP Response → Client

​

Subscription Flow (Real-time)

1. Client: GET /api/records/v1/{api_name}/subscribe/{record_id}
2. Server: Establish SSE connection
3. SQLite: Create trigger for record changes
4. On Change: Notify subscription manager
5. Server: Send event to client over SSE

​

Configuration System

​

Extension System

• JSON Schema Functions: Validation against JSON schemas
• UUID Functions: UUIDv7 generation
• GeoIP: MaxMind database queries for IP geolocation
• Custom Functions: User-defined functions via WASM

​

Performance Considerations

1. Connection Pooling: Reuses SQLite connections across requests
2. Metadata Caching: Schema information cached in memory
3. Read Thread Pool: Multiple reader threads for concurrent queries
4. Query Preparation: Cached prepared statements
5. Reactive Updates: Only rebuilds affected state on config changes
6. WASM Compilation: Component-level caching for WASM modules

​

Security Architecture

• JWT-based Authentication: EdDSA signed tokens
• CSRF Protection: Random tokens validated on state-changing operations
• Row-Level Security: SQL-based access rules per operation
• Rate Limiting: IP-based throttling on auth endpoints
• Sandboxed WASM: Isolated execution with controlled host functions

​

Next Steps