ForgeLM/.planning/codebase/STRUCTURE.md

Codebase Structure

Analysis Date: 2026-03-28

Directory Layout

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