# Codebase Structure

**Analysis Date:** 2026-03-28

## Directory Layout

```text
ForgeLM/
├── crates/              # Rust workspace crates for backend, engine, CLI, contracts, metrics, FFI
├── tauri-app/           # Desktop application with React frontend and Tauri Rust backend
├── docs/                # Product, API, CLI, and developer documentation
├── experiments/         # Benchmarks and exploratory scripts
├── models/              # Local model assets and model notes
├── scripts/             # Build helpers
├── target/              # Cargo build artifacts
└── ui/                  # Standalone HTML chat prototype
```

## Directory Purposes

**`crates/api-contracts/`:**
- Purpose: Shared API payload definitions
- Contains: request/response/error model types
- Key files: `crates/api-contracts/src/chat.rs`, `crates/api-contracts/src/models.rs`, `crates/api-contracts/src/health.rs`

**`crates/inference-core/`:**
- Purpose: Inference engine and generation pipeline
- Contains: engine/session/profile/sampler code
- Key files: `crates/inference-core/src/engine.rs`, `crates/inference-core/src/session.rs`, `crates/inference-core/src/profile.rs`

**`crates/inference-server/`:**
- Purpose: Public local HTTP API
- Contains: Axum bootstrap, routes, compatibility logic
- Key files: `crates/inference-server/src/main.rs`, `crates/inference-server/src/routes.rs`, `crates/inference-server/src/compat.rs`

**`crates/localllm-cli/`:**
- Purpose: CLI control surface
- Contains: parser, execution preview, live transport, tests in one file
- Key files: `crates/localllm-cli/src/main.rs`

**`tauri-app/src/`:**
- Purpose: Desktop frontend
- Contains: app shell, components, feature hooks, local persistence, CSS
- Key files: `tauri-app/src/App.tsx`, `tauri-app/src/components/ChatView.tsx`, `tauri-app/src/features/runtime/useRuntimeManager.ts`

**`tauri-app/src-tauri/src/`:**
- Purpose: Desktop backend bridge
- Contains: runtime lifecycle, GPU/model file commands, Tauri entry points
- Key files: `tauri-app/src-tauri/src/lib.rs`, `tauri-app/src-tauri/src/runtime/mod.rs`, `tauri-app/src-tauri/src/model_files.rs`

## Key File Locations

**Entry Points:**
- `crates/inference-server/src/main.rs`: local HTTP API binary
- `crates/localllm-cli/src/main.rs`: CLI binary
- `tauri-app/src/main.tsx`: React bootstrap
- `tauri-app/src-tauri/src/main.rs`: Tauri desktop bootstrap

**Configuration:**
- `Cargo.toml`: Rust workspace members and shared dependencies
- `tauri-app/package.json`: frontend scripts and npm dependencies
- `tauri-app/vite.config.ts`: frontend dev/build config
- `tauri-app/src-tauri/tauri.conf.json`: desktop packaging/window config

**Core Logic:**
- `crates/inference-core/src/engine.rs`: GGUF load/warmup/context management
- `crates/inference-server/src/routes.rs`: endpoint behavior and streaming
- `tauri-app/src/components/ChatView.tsx`: chat request/stream/persistence loop
- `tauri-app/src/features/runtime/components/RuntimeSettingsDrawer.tsx`: runtime control plane UI

**Testing:**
- `tauri-app/src/features/runtime/components/RuntimeSurface.test.tsx`: runtime UI integration-style tests
- `tauri-app/src/features/runtime/runtime-settings-form.test.ts`: form helper tests
- `tauri-app/src/hooks/model-selection.test.ts`: model selection helper tests
- Rust tests are co-located inside source files such as `crates/api-contracts/src/chat.rs` and `tauri-app/src-tauri/src/runtime/health.rs`

## Naming Conventions

**Files:**
- Rust uses snake_case modules like `crates/inference-server/src/routes.rs`
- Frontend React components use PascalCase files like `tauri-app/src/components/Sidebar.tsx`
- Frontend hooks/utilities use camelCase or kebab-lite names like `tauri-app/src/hooks/useModels.ts` and `tauri-app/src/features/runtime/runtime-settings-form.ts`

**Directories:**
- Feature grouping is shallow and domain-oriented: `tauri-app/src/components/`, `tauri-app/src/features/runtime/`, `tauri-app/src/hooks/`, `tauri-app/src/lib/`

## Where to Add New Code

**New backend API feature:**
- HTTP route/handler: `crates/inference-server/src/routes.rs`
- Request validation/prompt compatibility: `crates/inference-server/src/compat.rs`
- Shared payload type: `crates/api-contracts/src/`
- Engine capability: `crates/inference-core/src/`

**New desktop runtime feature:**
- Frontend runtime UI or hook: `tauri-app/src/features/runtime/`
- New Tauri command/runtime backend support: `tauri-app/src-tauri/src/` or `tauri-app/src-tauri/src/runtime/`
- Shared runtime type mirrored to frontend: `tauri-app/src/features/runtime/types.ts`

**New chat/UI feature:**
- Chat behavior: `tauri-app/src/components/ChatView.tsx`
- Message rendering: `tauri-app/src/components/MessageBubble.tsx`
- Shared browser persistence: `tauri-app/src/lib/db.ts` or `tauri-app/src/lib/chat.ts`
- Styling: colocated CSS file in `tauri-app/src/components/` or `tauri-app/src/features/runtime/components/`

**Utilities:**
- Frontend shared helpers: `tauri-app/src/lib/` or feature-local helper file under `tauri-app/src/features/runtime/`
- Rust cross-cutting helpers: keep crate-local unless multiple crates need them; if shared at API boundary, prefer `crates/api-contracts/`

## Frontend / Design System Structure

**Styling model:**
- Use CSS custom properties from `tauri-app/src/index.css` as the de facto design token layer
- Keep component styling in per-component CSS files such as `tauri-app/src/components/Sidebar.css` and `tauri-app/src/components/ChatView.css`
- Reuse the same status colors, radius tokens, and surface variables instead of introducing ad hoc values

**Component organization:**
- Layout shell: `tauri-app/src/App.tsx`
- Global navigation and runtime entry: `tauri-app/src/components/Sidebar.tsx`
- Core chat surface: `tauri-app/src/components/ChatView.tsx`
- Atomic-ish content node: `tauri-app/src/components/MessageBubble.tsx`
- Runtime feature subdomain: `tauri-app/src/features/runtime/components/`

**State boundaries:**
- Runtime state lives in `tauri-app/src/features/runtime/useRuntimeManager.ts`
- Models state lives in `tauri-app/src/hooks/useModels.ts`
- Local DB readiness lives in `tauri-app/src/hooks/useDB.ts`
- Chat screen owns message and compose state locally in `tauri-app/src/components/ChatView.tsx`

## Special Directories

**`target/`:**
- Purpose: Cargo build artifacts and copied runtime DLLs
- Generated: Yes
- Committed: No

**`models/`:**
- Purpose: local GGUF assets and notes
- Generated: No
- Committed: Partially; README is committed, model binaries may be local-only depending on workflow

**`experiments/`:**
- Purpose: benchmarks, profiling, and exploratory performance work
- Generated: Mixed
- Committed: Yes

**`ui/`:**
- Purpose: standalone browser chat prototype separate from the Tauri frontend
- Generated: No
- Committed: Yes

---

*Structure analysis: 2026-03-28*