155 lines
6.7 KiB
Markdown
155 lines
6.7 KiB
Markdown
# 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*
|