Forge Desktop - Architecture Overview

Executive Summary

Forge is a cross-platform desktop application built with Tauri 2.x (Rust backend) and React (TypeScript frontend). It provides idea-to-execution tracking with visual mind mapping, goal management, task boards, and real-time collaboration features.

System Architecture

High-Level Architecture Diagram

How it works:

The data flows from top to bottom: User interacts with React → React calls Tauri commands → Tauri invokes Rust handlers → Rust communicates with external services.

Component Overview

1. Frontend Layer (React/TypeScript)

Technology Stack:

• React 19 with TypeScript
• Tailwind CSS for styling
• shadcn/ui component library
• React Query for server state management
• Zustand for client state management
• React Router for navigation
• Framer Motion for animations
• Lucide React for icons

Key Directories:

src/
├── components/     # Reusable UI components
│   ├── ui/         # shadcn/ui primitives
│   ├── dashboard/  # Dashboard-specific components
│   ├── shared/     # Shared components (ActivityFeed, etc.)
│   └── calling/    # LiveKit voice/video components
├── pages/          # Route pages
├── hooks/          # Custom React hooks
├── stores/         # Zustand state stores
├── lib/            # Utilities and API clients
└── types/          # TypeScript type definitions

2. Tauri Layer (IPC Bridge)

Tauri Plugins Used:

IPC Communication:

• Frontend calls Rust functions via invoke() from @tauri-apps/api/core
• Commands are defined with #[tauri::command] attribute
• Data is serialized/deserialized via Serde JSON

3. Backend Layer (Rust)

Key Modules:

src-tauri/src/
├── lib.rs              # App entry point, plugin registration
├── app_commands.rs     # App lifecycle commands (show window, init Turso)
├── commands.rs         # Settings, OAuth, LiveKit commands
├── turso_commands.rs   # CRUD operations for Ideas, Goals, Tasks
├── shared_commands.rs  # User presence and calling features
├── turso.rs            # Turso database connection and models
├── db.rs               # Local SQLite database
└── models.rs           # Local data models

State Management:

• TursoState - Lazy-initialized Turso database connection
• Database - Local SQLite for settings (legacy)

4. Data Layer

Turso (Shared Cloud Database):

• Primary database for all user data
• libSQL (SQLite-compatible) hosted on Turso cloud
• Supports multi-tenant architecture via tenant_id

Local SQLite:

• Used for LiveKit settings (legacy)
• Fast local storage for non-shared data

Tauri Plugin Store:

• Stores Turso and LiveKit credentials
• Persists across app reinstalls
• Located at ~/Library/Application Support/com.forge.desktop/settings.json

Data Flow Architecture

App Initialization Flow

How it works:

1. Window Hidden - The app window starts hidden to avoid showing a blank screen
2. Load Settings - React loads saved credentials from the Plugin Store (settings.json)
3. Initialize Turso - If credentials exist, React calls the Rust backend to connect to Turso
4. Connect to Database - Rust establishes connection and creates tables if needed
5. Show Window - Once connected, Rust shows the main window
6. Render UI - React renders the dashboard with data from Turso

CRUD Operation Flow

How it works:

1. React Component calls invoke("get_all_ideas") to request data
2. Tauri IPC routes the call to the corresponding Rust command
3. Rust Handler executes the #[tauri::command] function
4. Turso DB receives the libSQL query and returns result rows
5. Serde JSON serializes the Rust structs to JSON
6. Promise resolves in React with the data

OAuth Authentication Flow

How it works:

1. User clicks sign in - Initiates the OAuth flow
2. PKCE Generation - App generates a code_verifier for security (Proof Key for Code Exchange)
3. System Browser - Opens the default browser with Azure AD login URL
4. Azure Login - User enters their Microsoft credentials
5. Native Redirect - Azure redirects to forge://oauth/callback which the app handles via deep-link plugin
6. Token Exchange - App exchanges the authorization code for access and ID tokens
7. Extract Tenant - The tenant_id is extracted from the JWT to scope data to the user’s organization
8. Create User - User record is created/updated in Turso
9. Show Dashboard - Session is stored in Zustand and dashboard is displayed

Database Schema

Entity Relationship Diagram

How to read this diagram:

The lines show relationships between database tables. ||--o{ means “one-to-many” (one record on the left relates to many records on the right).

Multi-Tenancy

All queries are filtered by tenant_id to ensure data isolation between organizations:

SELECT * FROM ideas
WHERE author_id IN (
    SELECT id FROM users WHERE tenant_id = ?
)

This ensures users from one Microsoft 365 tenant cannot see data from another tenant.

Security Architecture

Authentication

Credential Storage

Content Security Policy

The app uses a strict CSP configured in tauri.conf.json:

default-src 'self';
connect-src 'self' ipc: http://ipc.localhost wss: https:;
img-src 'self' asset: http://asset.localhost data: blob: https:;
script-src 'self' 'unsafe-eval';
style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
font-src 'self' https://fonts.gstatic.com;

Real-time Features

User Presence

How it works:

1. Update Presence - The app periodically calls update_presence() to mark the user as online
2. Poll Database - Every 30 seconds, the app fetches the list of online users from Turso
3. Display - Online users are shown in the UI with their avatars
4. Timeout - Users who haven’t updated presence recently are marked as offline

Voice/Video Calling

How it works:

1. Caller initiates - Caller’s app creates a call record in Turso with create_call()
2. Callee polls - Callee’s app periodically checks Turso for incoming calls
3. Accept call - Callee accepts, updating the call status in Turso
4. WebRTC connection - Both apps connect to LiveKit Cloud using the LiveKit SDK
5. Media streaming - LiveKit handles the actual audio/video transmission via WebRTC

Technology Summary

Document Information