Electron Desktop App Architecture — Full Stack with AI (No Database)

Electron Desktop App Architecture — Full Stack with AI (No Database)

Architecture for an offline-first desktop application built with Electron, bundling a Next.js frontend, Express.js backend, and Python AI service — without any database or vector store. Data is stored in JSON files on disk.

Tech Stack

Layer Technology Purpose
Desktop Shell Electron Window management, IPC bridge, app:// protocol
Frontend Next.js (Pages Router) + TypeScript UI, routing, dual-path API client (IPC or fetch)
Styling Tailwind CSS + CSS variables Custom theme system with data-theme attribute
State React Context + Zustand + custom hooks Global state, complex UI state, server state
Backend Express.js + TypeScript REST API, file uploads (Multer), JSON file storage
AI Service Python FastAPI + Uvicorn Agents, tools, guardrails, MCP, orchestrator
Local LLM Any GGUF model via llama-cpp-python Offline AI generation
Cloud LLMs OpenAI, Anthropic, Gemini, DeepSeek, Groq Online AI generation
Licensing LemonSqueezy (via website middleman) License activation, validation, device management
Packaging electron-builder + PyInstaller Windows .exe / macOS .dmg

System Architecture

Request Flow

License Activation

  • Website is the API middleman (holds the LemonSqueezy API key)
  • Local JSON file stores activation state for offline use
  • 14-day offline grace period after last successful validation
  • Machine fingerprint prevents key sharing across devices

Dev vs Production

Aspect Dev Production (packaged)
Frontend http://localhost:3000 app://./index.html (static export)
Backend ts-node-dev index.ts node backend/dist/index.js
AI Service .venv/Scripts/python -m api.main aiservice.exe (PyInstaller)
Data backend/data/*.json AppData/Roaming/AppName/data/*.json
Uploads backend/uploads/ AppData/Roaming/AppName/uploads/
Detection app.isPackaged = false app.isPackaged = true

Build Commands

Command What It Does
npm run dev Backend + frontend in browser (localhost:3000)
npm run desktop Compiles all + launches Electron window
npm run pack Builds unpacked directory (for testing)
npm run dist:win Builds Windows distributable
npm run dist:mac Builds macOS distributable

File Structure

desktop-app/
├── frontend/
│   ├── api/                    # Dual-path API client (IPC + fetch)
│   ├── components/             # Shared reusable components
│   │   ├── ui/                 # Atoms (Button, Modal, VirtualList, etc.)
│   │   ├── layout/             # Container, Header, Sidebar
│   │   ├── forms/              # Checkbox, ColorPicker, FormField, etc.
│   │   └── data-display/       # EmptyState, Grid, List
│   ├── contexts/               # React Context providers
│   ├── hooks/                  # Custom hooks (per module)
│   ├── modules/                # Feature modules
│   ├── pages/                  # Next.js Pages Router
│   ├── services/               # Business logic layer
│   ├── store/                  # Zustand stores
│   ├── utils/                  # Per-module utilities
│   ├── styles/                 # Tailwind + CSS variable theme system
│   └── public/assets/          # Static assets (themes, images, fonts)
│
├── backend/
│   ├── index.ts                # Express entry point
│   ├── paths.ts                # Path utilities (dev vs packaged)
│   ├── routes/                 # Route groups
│   ├── services/               # Business logic (read/write JSON files)
│   ├── data/                   # JSON file storage (license.json, etc.)
│   └── uploads/                # File storage (fonts, music, images, themes)
│
├── aiservice/                  # Python AI Service (Flat Agent Layout)
│   ├── src/
│   │   └── appname_aiservice/
│   │       ├── api/            # FastAPI server + routes
│   │       ├── services/       # AI service helpers
│   │       ├── test_interface/ # Dev testing UI
│   │       ├── agents/         # One .py per agent + base.py
│   │       ├── tools/          # One .py per tool + base.py
│   │       ├── guardrails/     # Input/output validators, content filters
│   │       ├── mcp/
│   │       │   ├── clients/    # MCP client connections
│   │       │   └── servers/    # MCP server implementations
│   │       ├── orchestrator/   # Router + workflow coordination
│   │       └── config/         # Settings, agent & tool registries
│   ├── prompts/                # Prompt templates (system/, templates/, configs/)
│   ├── models/                 # Local LLM model (GGUF)
│   ├── data/                   # Runtime data
│   ├── pyproject.toml          # Python dependencies (uv)
│   └── build.py                # PyInstaller build script
│
├── electron/                   # Electron desktop wrapper
│   ├── main.ts                 # IPC handlers, service spawner, app:// protocol
│   └── preload.ts              # Secure bridge (window.electronAPI)
│
├── electron-builder.yml        # Packaging configuration
├── afterPack.js                # Post-build script
└── package.json                # Root scripts (dev, desktop, pack, dist)