Architecture

Flamingo is a modern desktop API client built with web technologies.

Tech Stack

Layer	Technology
Desktop Shell	Electron
UI Framework	React 18
Build Tool	Vite 5
Language	TypeScript
Styling	Tailwind CSS
State Management	Zustand
Code Editor	Monaco Editor
UI Primitives	Radix UI
Animations	Framer Motion
Icons	Lucide React
HTTP Client	Native Fetch API
Encryption	Web Crypto API (AES-256-GCM)

Project Structure

client/
├── electron/           # Electron main process & preload
├── src/
│   ├── main/           # App entry point & root component
│   ├── components/
│   │   ├── layout/     # TitleBar
│   │   ├── request/    # RequestBuilder, BodyEditor, KeyValueEditor
│   │   ├── response/   # ResponseViewer, ResponseCompare
│   │   ├── sidebar/    # Sidebar panels (collections, history, etc.)
│   │   ├── ui/         # Reusable UI primitives
│   │   └── workspace/  # TabBar, CommandPalette
│   ├── stores/         # Zustand stores (tabs, settings, collections, etc.)
│   ├── lib/            # Utilities, types, cURL parser, script runner, sync
│   └── styles/         # Global CSS with Tailwind

Data Flow

User Action → Component → Zustand Store → localStorage (persist)
                              ↓
                   (if sync enabled)
                              ↓
                      Sync Client → Encrypt → Server API

State Management

Each domain has its own Zustand store with persist middleware:

Store	Data	Persistence Key
tab-store	Open tabs, requests	flamingo-tabs
settings-store	App settings	flamingo-settings
collection-store	Request collections	flamingo-collections
environment-store	Environments & variables	flamingo-environments
history-store	Request history	flamingo-history
ui-store	Sidebar state	flamingo-ui
theme-store	Theme preference	flamingo-theme

Request Lifecycle

1. User clicks Send or presses Ctrl + Enter
2. Environment variables are resolved in URL, headers, params, and body
3. Pre-request script is executed (if defined)
4. HTTP request is sent via fetch()
5. Response is captured (status, headers, body, timing, size)
6. Post-response script is executed (if defined)
7. History entry is added
8. Response is displayed in the viewer panel

Script Execution

Scripts run in a sandboxed context using new Function():

• Pre-request: receives console and request objects
• Post-response: receives console, request, and response objects
• All console output is captured as structured logs

Electron Main Process

The main process (electron/main.js) creates a frameless BrowserWindow with hidden title bar and custom window controls:

• Default size: 1400 × 900 (minimum 900 × 600)
• webSecurity: false — same-origin policy is disabled to allow cross-origin requests from the API client
• DevTools: auto-opens in development mode
• macOS: app stays alive when all windows close (platform convention)

Four IPC channels are exposed via the preload script’s context bridge:

Channel	Direction	Purpose
window-minimize	Renderer → Main	Minimize window
window-maximize	Renderer → Main	Maximize/restore window
window-close	Renderer → Main	Close window
open-external	Renderer → Main	Open URL in default browser

The preload script (electron/preload.js) exposes a secure window.electronAPI object with minimize(), maximize(), close(), and openExternal(url) methods.

Sync Architecture

Sync works through an OAuth-like flow:

1. User enters server URL and clicks Connect
2. Browser opens for authentication on the sync server
3. User approves the connection
4. Client polls for session token
5. Encryption keys are generated and exchanged
6. Data sync begins bidirectionally

Data is encrypted with AES-256-GCM before leaving the device. The sync server (Next.js + Supabase) only stores encrypted blobs.