Appearance
Monorepo Map
Haptique is a TypeScript monorepo using npm workspaces and Turbo for build orchestration. This page is the complete directory inventory — every top-level directory, its purpose, and its key files.
Directory Tree
nfs_haptique/
+-- apps/
| +-- server/ # HOS Hub (Node/Express/Electron) + Fleet Manager UI
| +-- mobile/ # Expo/React Native app
| +-- llama-service/ # Local AI inference engine (llama.cpp)
| +-- mcp-driver-builder/ # MCP server for AI-generated OS-local driver packages
| +-- tv/ # HOS for Android TV / Apple TV
+-- packages/
| +-- shared/ # Shared TypeScript types
+-- sdk/ # Driver SDK (lib + docs + samples)
+-- docs/ # Internal architecture docs
+-- marketing/ # Marketing assets
+-- scripts/ # Utility scripts
+-- wiki/ # This developer wiki (VitePress)apps/server/
Purpose: Haptique OS Hub — the central Node/Express/Electron server. Runs the driver runtime, REST API, SSE state stream, Socket.IO channels, OS web UI, and the Fleet Manager UI.
Key files:
| File / Directory | Role |
|---|---|
index.ts | Server entry point — bootstraps Electron or headless mode |
main.ts | Electron main process |
src/server.ts | Express application setup |
src/routes/ | REST route handlers (OS API, app API, remote API, integrations, fleet) |
src/core/DriverWSServer | Raw WebSocket server accepting driver connections on /driver |
src/core/ProtocolHub | Internal event bus distributing device events to all consumers |
src/bridge/ActionDispatcher | Routes device commands to the correct driver |
src/drivers/JavaScriptDriverProcess.ts | OS-local JavaScript driver runtime for uploaded .js packages |
src/state/DeviceStateManager | In-memory device state store |
For a deep dive into these modules, see Server Internals.
apps/llama-service/
Purpose: Local AI inference engine wrapping llama.cpp. Provides GGUF model execution, token streaming, and resource management.
Key files:
| File / Directory | Role |
|---|---|
index.ts | Service entry point |
src/inference.ts | Llama.cpp binding and inference loop |
models/ | Local storage for GGUF model files |
apps/mcp-driver-builder/
Purpose: MCP server that lets AI assistants generate reviewable Haptique OS local driver packages. It targets the OS Integration Manager upload flow and preserves the separate Fleet cloud integration path.
Key files:
| File / Directory | Role |
|---|---|
src/index.ts | MCP server entry point and tool registration |
src/builder.ts | Manifest generation, code templates, validation, and ZIP packaging |
src/schema.ts | Manifest schemas, protocol reference, and tool types |
README.md | Local build/run instructions |
Runtime outputs are python, lua, and first-class local javascript packages. TypeScript output must be compiled to .js before upload.
For the detailed workflow, see AI Driver Builder MCP.
apps/tv/
Purpose: Haptique OS client for smart TV platforms (Android TV, Apple TV). Built with React Native for TV.
apps/mobile/
Purpose: Expo/React Native mobile app for controlling devices, managing rooms, running scenes, and designing layouts.
Key files:
| File / Directory | Role |
|---|---|
App.tsx | Root navigator and auth flow |
src/contexts/HaptiqueContext.tsx | Controller session state, bootstrap, command dispatch, primary SSE connection |
src/contexts/ThemeContext.tsx | App theming |
src/features/controls/ | Device control screens |
src/features/rooms/ | Room management |
src/features/media/ | Media playback controls |
src/features/scenes/ | Scene triggering |
src/features/designer/ | Interface layout designer |
For a deep dive into navigation and data flow, see Mobile App.
packages/shared/
Purpose: Shared TypeScript types and helpers consumed by both apps/server and apps/mobile. This is the canonical source of type definitions for API payloads, device models, and command shapes.
Key files:
| File | Role |
|---|---|
src/index.ts | Single export surface for all shared types |
sdk/
Purpose: HOS Driver SDK — a TypeScript helper library, developer documentation, and sample drivers. Designed for external driver authors who want to build integrations without touching the HOS server codebase.
Key files:
| File / Directory | Role |
|---|---|
lib/hos-driver.ts | HosDriver class — main SDK entry point for driver authors |
lib/types.ts | Mirrored protocol types aligned with packages/shared |
docs/ | External-facing developer guides (getting started, architecture, domain reference, troubleshooting) |
samples/ | Runnable sample drivers across 5 device domains |
Note:
sdk/docs/contains the external-facing driver SDK documentation. It is separate from this wiki — the SDK docs are for external driver authors; this wiki is for internal developers working on the Haptique codebase itself.
docs/
Purpose: Internal architecture documentation (not published externally). Written against the actual code in this repository.
Key files:
| File | Role |
|---|---|
frontend-backend-architecture.md | Comprehensive server + mobile architecture narrative — API surfaces, transport model, auth flows |
dev-vs-production.md | Differences between development and production environments |
marketing/
Purpose: Marketing assets for the Haptique product (branding, copy, screenshots, etc.).
scripts/
Purpose: Root-level utility and build scripts used during development and CI.
wiki/
Purpose: This developer wiki — a VitePress static site hosted locally. Run npm run dev inside this directory to start the local documentation server.
Key files:
| File | Role |
|---|---|
docs/ | Markdown content pages |
docs/.vitepress/config.ts | Site configuration, sidebar navigation, theme settings |
package.json | dev, build, and preview scripts |
Workspace Configuration
The root package.json defines npm workspaces:
json
"workspaces": [
"apps/*",
"packages/*",
"sdk"
]This covers apps/server, apps/mobile, packages/shared, and sdk. Dependencies are hoisted to the root node_modules/.
wiki/is intentionally NOT a workspace. It runs standalone —cd wiki && npm installandnpm run dev. This prevents the VitePress dev server from being included in Turbo's workspace-widedevtask, which would clutter the development workflow.
Turbo Build Orchestration
turbo.json at the repo root orchestrates build, dev, lint, and typecheck tasks across all workspaces. It handles dependency ordering between packages (e.g., packages/shared must build before apps/server).
The wiki is excluded from Turbo's pipeline — always invoke it directly:
bash
cd wiki
npm run dev # start local dev server
npm run build # production build
npm run preview # preview production build