# samarthsaxena2004/flickai architecture

> Architecture diagram of the GitHub repository samarthsaxena2004/flickai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samarthsaxena2004/flickai
- Repository: https://github.com/samarthsaxena2004/flickai

## Overview

1. **Monorepo shape**
   - This repo is split into two independently runnable applications plus shared packages.
   - `apps/desktop` is the product: an Electron desktop assistant.
   - `apps/web` is the marketing/landing site built with Next.js.
   - `packages/*` holds reusable code, mainly shared UI primitives and a typed API client.

2. **Desktop app boundary**
   - `apps/desktop/electron/main.ts` is the Electron main process: it owns the native app lifecycle, window creation, and OS-level behaviors.
   - `apps/desktop/electron/preload.ts` is the security boundary between the main process and the React UI, exposing only safe APIs to the renderer.
   - `apps/desktop/src/*` is the renderer process: all visible assistant UI lives here.

3. **Desktop UI flow**
   - The renderer is a React + Vite app.
   - `App.tsx`, `MessageBubble.tsx`, and `SettingsModal.tsx` suggest a chat-style assistant with configurable provider settings.
   - The UI is designed around streaming responses, with assistant output appearing incrementally rather than as a single blocked reply.

4. **AI interaction subsystem**
   - `src/hooks/useAI.ts` is the central orchestration hook for sending prompts and receiving model output.
   - The README indicates the model backend is Cerebras GLM-4.7, with the API client package likely wrapping that integration.
   - The architectural emphasis is low-latency inference so the desktop assistant feels “instant.”

5. **Vision subsystem**
   - `src/hooks/useVision.ts` handles screen/image context gathering.
   - The README describes active-window or full-screen capture, with OpenRouter/Llama 3.2 Vision and Tesseract.js OCR as the vision path and fallback.
   - This creates a distinct input pipeline separate from plain text chat: screen context is converted into model-readable prompt material.

6. **Voice input subsystem**
   - `src/hooks/useVoiceInput.ts` handles speech-to-text.
   - Deepgram is the external transcription service, so voice is another input channel feeding the same assistant conversation flow.
   - The result is a multimodal desktop assistant: text, voice, and screen context converge into one response stream.

7. **Desktop runtime responsibilities**
   - Electron gives the app native windowing and OS integration, which is important because the product is meant to be summoned globally and run outside the browser.
   - The main process likely owns the hotkey/wake behavior described in the README, while the renderer handles interaction and presentation.
   - This separation is the key trust boundary: native capabilities stay in Electron, UI logic stays in React.

8. **Web app boundary**
   - `apps/web` is a separate Next.js 15 App Router application, used for the public site rather than the desktop assistant itself.
   - It is mostly composed of marketing sections: hero, how-it-works, pricing, testimonials, FAQ, footer, and CTA.
   - The many `bento-*` components and animated sections indicate a presentation-heavy, mostly static frontend.

9. **Web app composition**
   - The web app uses local UI components plus shadcn-style primitives under `components/ui`.
   - `theme-provider.tsx` suggests client-side theme toggling/dark mode support.
   - There is also a `lib/supabase.ts`, which marks an external backend integration point even if it is not central to the core assistant workflow.

10. **Shared packages**
   - `packages/api-client` centralizes typed access to the AI backend, especially Cerebras-related calls and shared request/response types.
   - `packages/ui` provides reusable UI controls such as `Button` and `Toggle`.
   - These packages reduce duplication across apps and create explicit boundaries between “shared primitives” and app-specific code.

11. **Data flow across the system**
   - In the desktop app, user actions enter through the renderer UI, optional voice/vision hooks enrich the prompt, the API client sends the request to external AI services, and the streamed answer is rendered back into message bubbles.
   - In the web app, content flow is mostly one-way: structured components render static/product storytelling content for the landing page.
   - The repo therefore has one interactive AI runtime and one mostly static promotional frontend.

12. **Build and deployment topology**
   - `pnpm-workspace.yaml`, `turbo.json`, and the root `package.json` show a Turborepo-managed workspace with shared dependency installation via PNPM.
   - `vercel.json` indicates the web app is intended for Vercel-style deployment.
   - The desktop app is a separate Electron build target with its own environment variables for API keys.

Main entry points: [`apps/desktop/src/App.tsx`](https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/src/App.tsx) (Assistant UI), [`package.json`](https://github.com/samarthsaxena2004/flickai/blob/main/package.json) (FlickAI), [`apps/web/app/page.tsx`](https://github.com/samarthsaxena2004/flickai/blob/main/apps/web/app/page.tsx) (Landing page), [`apps/desktop/electron/main.ts`](https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/electron/main.ts) (Electron main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Workspace"]
  node_root["FlickAI<br/>workspace<br/>[package.json]"]
  node_pnpm["PNPM<br/>workspace tool"]
  node_turbo["Turbo<br/>build orchestrator<br/>[turbo.json]"]
end

subgraph group_desktop["Desktop app"]
  node_desktop_main["Electron main<br/>native runtime<br/>[main.ts]"]
  node_desktop_preload["Preload bridge<br/>security bridge<br/>[preload.ts]"]
  node_desktop_app["Assistant UI<br/>renderer app<br/>[App.tsx]"]
  node_message_bubble["Message bubble<br/>chat component<br/>[MessageBubble.tsx]"]
  node_settings_modal["Settings modal<br/>config component<br/>[SettingsModal.tsx]"]
  node_use_ai["AI hook<br/>orchestration hook<br/>[useAI.ts]"]
  node_use_vision["Vision hook<br/>multimodal input<br/>[useVision.ts]"]
  node_use_voice["Voice hook<br/>speech input<br/>[useVoiceInput.ts]"]
end

subgraph group_web["Web app"]
  node_web_app["Landing page<br/>next app<br/>[page.tsx]"]
  node_hero["Hero section<br/>marketing section<br/>[hero-section.tsx]"]
  node_pricing["Pricing section<br/>marketing section"]
  node_theme["Theme provider<br/>client provider<br/>[theme-provider.tsx]"]
end

subgraph group_shared["Shared packages"]
  node_api_client["API client<br/>typed client<br/>[index.ts]"]
  node_cerebras["Cerebras integration<br/>provider adapter<br/>[cerebras.ts]"]
  node_ui_pkg["UI package<br/>shared components<br/>[index.ts]"]
  node_button["Button<br/>primitive<br/>[Button.tsx]"]
  node_toggle["Toggle<br/>primitive<br/>[Toggle.tsx]"]
end

node_root -->|"contains"| node_desktop_main
node_root -->|"contains"| node_web_app
node_root -->|"shares"| node_api_client
node_root -->|"shares"| node_ui_pkg
node_pnpm -->|"manages"| node_root
node_turbo -->|"builds"| node_desktop_main
node_turbo -->|"builds"| node_web_app
node_desktop_main -->|"loads"| node_desktop_preload
node_desktop_main -->|"creates window"| node_desktop_app
node_desktop_preload -->|"exposes api"| node_desktop_app
node_desktop_app -->|"renders"| node_message_bubble
node_desktop_app -->|"configures"| node_settings_modal
node_desktop_app -->|"orchestrates"| node_use_ai
node_desktop_app -->|"adds context"| node_use_vision
node_desktop_app -->|"accepts input"| node_use_voice
node_use_ai -->|"calls"| node_api_client
node_api_client -->|"adapts"| node_cerebras
node_ui_pkg -->|"exports"| node_button
node_ui_pkg -->|"exports"| node_toggle
node_web_app -->|"composes"| node_hero
node_web_app -->|"composes"| node_pricing
node_web_app -->|"provides"| node_theme

click node_root "https://github.com/samarthsaxena2004/flickai/blob/main/package.json"
click node_pnpm "https://github.com/samarthsaxena2004/flickai/blob/main/pnpm-workspace.yaml"
click node_turbo "https://github.com/samarthsaxena2004/flickai/blob/main/turbo.json"
click node_desktop_main "https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/electron/main.ts"
click node_desktop_preload "https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/electron/preload.ts"
click node_desktop_app "https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/src/App.tsx"
click node_message_bubble "https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/src/components/MessageBubble.tsx"
click node_settings_modal "https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/src/components/SettingsModal.tsx"
click node_use_ai "https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/src/hooks/useAI.ts"
click node_use_vision "https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/src/hooks/useVision.ts"
click node_use_voice "https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/src/hooks/useVoiceInput.ts"
click node_api_client "https://github.com/samarthsaxena2004/flickai/blob/main/packages/api-client/src/index.ts"
click node_cerebras "https://github.com/samarthsaxena2004/flickai/blob/main/packages/api-client/src/cerebras.ts"
click node_ui_pkg "https://github.com/samarthsaxena2004/flickai/blob/main/packages/ui/src/index.ts"
click node_button "https://github.com/samarthsaxena2004/flickai/blob/main/packages/ui/src/Button.tsx"
click node_toggle "https://github.com/samarthsaxena2004/flickai/blob/main/packages/ui/src/Toggle.tsx"
click node_web_app "https://github.com/samarthsaxena2004/flickai/blob/main/apps/web/app/page.tsx"
click node_hero "https://github.com/samarthsaxena2004/flickai/blob/main/apps/web/components/hero-section.tsx"
click node_pricing "https://github.com/samarthsaxena2004/flickai/blob/main/apps/web/components/pricing-section.tsx"
click node_theme "https://github.com/samarthsaxena2004/flickai/blob/main/apps/web/components/theme-provider.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root,node_pnpm,node_turbo toneBlue
class node_desktop_main,node_desktop_preload,node_desktop_app,node_message_bubble,node_settings_modal,node_use_ai,node_use_vision,node_use_voice toneAmber
class node_web_app,node_hero,node_pricing,node_theme toneMint
class node_api_client,node_cerebras,node_ui_pkg,node_button,node_toggle toneRose
```

## Components

### Workspace

Monorepo orchestration and shared packages

- [FlickAI](https://github.com/samarthsaxena2004/flickai/blob/main/package.json): workspace · Turborepo-managed monorepo with desktop, web, and shared packages · `package.json`
- [PNPM](https://github.com/samarthsaxena2004/flickai/blob/main/pnpm-workspace.yaml): workspace tool · Shared dependency and workspace installation layer · `pnpm-workspace.yaml`
- [Turbo](https://github.com/samarthsaxena2004/flickai/blob/main/turbo.json): build orchestrator · Task pipeline and repo-wide build coordination · `turbo.json`

### Desktop app

Electron assistant runtime and renderer UI

- [Electron main](https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/electron/main.ts): native runtime · Owns app lifecycle, windows, and OS integration · `apps/desktop/electron/main.ts`
- [Preload bridge](https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/electron/preload.ts): security bridge · Exposes a narrow API surface from Electron to the renderer · `apps/desktop/electron/preload.ts`
- [Assistant UI](https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/src/App.tsx): renderer app · React renderer for the desktop assistant experience · `apps/desktop/src/App.tsx`
- [Message bubble](https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/src/components/MessageBubble.tsx): chat component · Renders assistant and user messages in the conversation stream · `apps/desktop/src/components/MessageBubble.tsx`
- [Settings modal](https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/src/components/SettingsModal.tsx): config component · Provider and assistant settings UI · `apps/desktop/src/components/SettingsModal.tsx`
- [AI hook](https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/src/hooks/useAI.ts): orchestration hook · Central prompt and streaming-response coordination · `apps/desktop/src/hooks/useAI.ts`
- [Vision hook](https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/src/hooks/useVision.ts): multimodal input · Captures screen or image context and prepares vision prompts · `apps/desktop/src/hooks/useVision.ts`
- [Voice hook](https://github.com/samarthsaxena2004/flickai/blob/main/apps/desktop/src/hooks/useVoiceInput.ts): speech input · Handles speech-to-text transcription for the assistant · `apps/desktop/src/hooks/useVoiceInput.ts`

### Web app

Next.js marketing site

- [Landing page](https://github.com/samarthsaxena2004/flickai/blob/main/apps/web/app/page.tsx): next app · Public marketing site built with Next.js App Router · `apps/web/app/page.tsx`
- [Hero section](https://github.com/samarthsaxena2004/flickai/blob/main/apps/web/components/hero-section.tsx): marketing section · Top-of-page product story and conversion entry point · `apps/web/components/hero-section.tsx`
- [Pricing section](https://github.com/samarthsaxena2004/flickai/blob/main/apps/web/components/pricing-section.tsx): marketing section · Plans and purchase framing · `apps/web/components/pricing-section.tsx`
- [Theme provider](https://github.com/samarthsaxena2004/flickai/blob/main/apps/web/components/theme-provider.tsx): client provider · Client-side theme and dark mode handling · `apps/web/components/theme-provider.tsx`

### Shared packages

Reusable UI and typed API client

- [API client](https://github.com/samarthsaxena2004/flickai/blob/main/packages/api-client/src/index.ts): typed client · Shared typed access to the model backend and request/response types · `packages/api-client/src/index.ts`
- [Cerebras integration](https://github.com/samarthsaxena2004/flickai/blob/main/packages/api-client/src/cerebras.ts): provider adapter · Model-specific client logic for the low-latency backend · `packages/api-client/src/cerebras.ts`
- [UI package](https://github.com/samarthsaxena2004/flickai/blob/main/packages/ui/src/index.ts): shared components · Reusable primitives for both apps · `packages/ui/src/index.ts`
- [Button](https://github.com/samarthsaxena2004/flickai/blob/main/packages/ui/src/Button.tsx): primitive · Shared button control · `packages/ui/src/Button.tsx`
- [Toggle](https://github.com/samarthsaxena2004/flickai/blob/main/packages/ui/src/Toggle.tsx): primitive · Shared toggle control · `packages/ui/src/Toggle.tsx`

## Connections

- FlickAI → Electron main: contains · Workspace includes the Electron runtime
- FlickAI → Landing page: contains · Workspace includes the public site
- FlickAI → API client: shares · Shared packages are consumed by apps
- FlickAI → UI package: shares · Shared UI primitives are consumed by apps
- PNPM → FlickAI: manages · Workspace dependency resolution
- Turbo → Electron main: builds · Coordinates app tasks
- Turbo → Landing page: builds · Coordinates app tasks
- Electron main → Preload bridge: loads · Main process injects the preload bridge
- Electron main → Assistant UI: creates window · Main process hosts the renderer UI
- Preload bridge → Assistant UI: exposes api · Safe IPC boundary for renderer access
- Assistant UI → Message bubble: renders · Conversation stream is displayed through message bubbles
- Assistant UI → Settings modal: configures · Assistant settings are edited in a modal
- Assistant UI → AI hook: orchestrates · Renderer delegates prompt/response flow to the AI hook
- Assistant UI → Vision hook: adds context · Screen or image context can be attached to a prompt
- Assistant UI → Voice hook: accepts input · Speech input feeds the assistant flow
- AI hook → API client: calls · Model requests go through the typed client
- API client → Cerebras integration: adapts · Backend-specific Cerebras integration
- UI package → Button: exports · Shared primitive export
- UI package → Toggle: exports · Shared primitive export
- Landing page → Hero section: composes · Landing page is built from marketing sections
- Landing page → Pricing section: composes · Landing page is built from marketing sections
- Landing page → Theme provider: provides · Theme provider wraps client UI
