Project Structure

Project Structure

Walkthrough of the TitanX repository layout, the 3-process model enforced by folder boundaries, and where different kinds of code belong.

---

Top-level

TitanX/
├── src/               # Source code (main, renderer, worker)
├── docs/              # Technical documentation + ADRs
├── scripts/           # Build, install, release helpers
├── locales/           # i18n translation files (10 languages)
├── public/            # Static assets for the renderer
├── resources/         # Electron build resources (icons, entitlements)
├── patches/           # Patch-package patches for node_modules
├── examples/          # Integration examples
├── .claude/skills/    # Project conventions + skills for AI collaborators
├── electron-builder.yml
├── electron.vite.config.ts
├── package.json
└── readme.md

---

src/ — the source tree

Three processes, each with its own folder. No cross-process imports. Enforced by TypeScript path aliases + compiler checks.

src/process/ — main process (Node.js + Electron APIs)

src/process/
├── agent/            # LLM provider adapters (Claude, Gemini, OpenAI, etc.)
├── channels/         # Channel manager + per-backend runtime channels
├── team/             # Team orchestration (TeammateManager, MCP server, etc.)
├── task/             # Conversation + agent manager (ACP + API)
├── services/         # Service layer
│   ├── database/     # SQLite driver + 73 migrations
│   ├── fleetConfig/  # Config-bundle build + apply
│   ├── fleetCommands/# Signed-command dispatch + execute
│   ├── fleetTelemetry/# Telemetry push + ingest
│   ├── fleetLearning/# Dream Mode — push, ingest, dream scheduler
│   ├── iamPolicies/
│   ├── activityLog/
│   ├── agentGallery/
│   ├── reasoningBank/
│   ├── agentMemory/
│   ├── agentPlanning/
│   ├── secrets/
│   ├── tracing/
│   └── ...
├── webserver/        # Fleet webserver (master only)
├── worker/           # Child-fork workers for CPU-heavy tasks
├── extensions/       # Plugin registry
├── utils/            # Shared process-layer utilities
└── ...

Rules:

• Full Node.js API access (filesystem, child_process, networking)
• Full Electron main-process APIs (BrowserWindow, dialog, app)
• No React, no DOM, no browser APIs
• No imports from src/renderer/

src/renderer/ — renderer process (Chromium sandbox + React)

src/renderer/
├── pages/            # Route-level views (team, conversation, settings, gallery, ...)
├── components/       # Shared UI components
│   ├── layout/       # Titlebar, sidebar, etc.
│   ├── settings/
│   ├── fleet/        # Fleet-specific UI
│   └── ...
├── hooks/            # Custom React hooks
├── services/         # Renderer-side services (i18n, theming, ...)
├── styles/           # Global CSS (minimal)
└── ...

Rules:

• Full React + DOM + browser APIs
• UI library: @arco-design/web-react (no raw <button>, <input>, <select>)
• Styling: UnoCSS (utility classes) for 80%; CSS Modules for complex components
• Icons: @icon-park/react
• No Node.js APIs directly (no fs, no child_process)
• No imports from src/process/
• Calls to main process go through ipcBridge.<namespace>.<action>.invoke(...) (typed)

src/common/ — shared between processes

src/common/
├── types/            # Shared TypeScript types
│   ├── teamTypes.ts
│   ├── acpTypes.ts
│   ├── fleetTypes.ts
│   └── ...
├── adapter/
│   ├── ipcBridge.ts  # THE boundary — every IPC channel declared here
│   └── ...
├── utils/            # Pure utility functions (no side effects)
├── config/           # App-wide config constants
└── ...

Rules:

• Pure TypeScript — no filesystem, no DOM
• Compiles for both main + renderer targets
• Primary purpose: keep types + pure utilities consistent across the boundary

src/preload.ts — the IPC boundary

Tiny file that exposes the allowed IPC channels to the renderer via contextBridge. Every main-process-accessible function the renderer needs is declared here.

Changes here = widening the attack surface. Reviewed carefully.

---

docs/ — technical documentation

docs/
├── tech/             # Architecture, design decisions at high level
├── conventions/      # Code style, file structure, PR automation
├── adr/              # Architecture Decision Records (numbered, append-only)
├── feature/          # Per-feature deep-dives (fleet/, iam/, ...)
├── research/         # Exploratory notes, experiments
├── readme/           # Supporting docs referenced from main readme
├── screenshots/      # Product screenshots + architecture GIF
├── diagrams/         # HTML animated diagrams + generated GIFs
├── development.md    # Dev setup canonical doc
└── CODE_STYLE.md     # Deeper style rules beyond AGENTS.md

docs/ vs. wiki — the wiki is human-facing (guided tutorials, evaluators, operators); docs are reference + authoritative (contributors). Wiki summarizes + links to docs; never the reverse.

---

scripts/ — automation

scripts/
├── build-with-builder.js   # Electron builder orchestration
├── afterPack.js            # Post-package hook (native module rebuild)
├── afterSign.js            # Post-sign hook (notarization if configured)
├── pr-automation.sh        # PR review + fix + merge daemon
├── check-i18n.js           # Validate translation consistency
├── generate-i18n-types.js  # Generate type defs from locales
├── install-ubuntu.sh       # One-shot Ubuntu install
├── prepareBundledBun.js    # Bundle Bun with the app for worker processes
├── rebuildNativeModules.js # Native module handler per-arch
└── ...

---

locales/ — i18n

One folder per locale, each with per-module translation files:

locales/
├── en-US/
│   ├── common.json
│   ├── team.json
│   ├── fleet.json
│   ├── dream.json
│   └── ...
├── zh-CN/
├── ja-JP/
└── ... (10 locales)

All user-facing strings use t(key) from react-i18next. Validated on every CI run.

See the i18n skill in .claude/skills/i18n/SKILL.md.

---

.claude/skills/ — collaborator conventions

Skills for AI contributors (and humans reading them):

.claude/skills/
├── architecture/       # File structure rules, layering
├── i18n/               # i18n workflow
├── testing/            # Vitest setup, coverage, conventions
├── oss-pr/             # PR workflow, commit format
├── pr-review/          # How PRs get reviewed
├── pr-fix/             # How review issues get fixed
├── pr-automation/      # The automated pipeline orchestrator
└── ...

---

The directory size rule

From AGENTS.md:

A single directory must not exceed 10 direct children.

When a folder hits 10, split by responsibility. Example: src/process/services/ was a flat folder until ~12 services, then split into subfolders per service.

This keeps the tree browseable + encourages thoughtful organization over "just pile it in".

---

Naming conventions

Artifact	Convention	Example
Components (TSX)	PascalCase	ChatPanel.tsx
Utilities	camelCase	formatDate.ts
Hooks	use + camelCase	useTheme.ts
Constants files	camelCase	constants.ts (UPPER_SNAKE_CASE inside)
Type files	camelCase	teamTypes.ts
Style files	kebab-case or Component.module.css	chat-panel.module.css
Unused params	_ prefix	_unused

---

Path aliases

TypeScript + Vite configure these aliases:

Alias	Resolves to
@/	src/
@process/	src/process/
@renderer/	src/renderer/
@worker/	src/process/worker/
@common/	src/common/

Always use aliases for cross-folder imports. Relative paths are fine within the same folder.

---

Where to put a new...

New UI component used in multiple pages

→ src/renderer/components/<domain>/ComponentName.tsx

New page (route-level)

→ src/renderer/pages/<pagename>/index.tsx

New service in main process

→ src/process/services/<serviceName>/index.ts (create folder, not single file)

New database migration

→ Add to src/process/services/database/migrations.ts as migration_vNN; bump CURRENT_DB_VERSION in schema.ts

New IPC channel

→ src/common/adapter/ipcBridge.ts (declare) + handler in main process + consumer in renderer

New type shared across processes

→ src/common/types/<domain>Types.ts

New ACP runtime integration

→ src/common/types/acpTypes.ts (register) + detection in src/process/services/acpDetection/

New MCP server integration

→ src/process/services/mcp-servers/<name>/ following the MCP SDK

New skill for AI collaborators

→ .claude/skills/<skillName>/SKILL.md

New locale string

→ Every locales/<locale>/<module>.json + run bun run i18n:types

---

Related pages

• Development Setup — how to build + run
• Code Conventions — style rules in depth
• Testing — Vitest conventions
• Architecture Overview — the 3-process model conceptually
• docs/conventions/file-structure.md — canonical source