# Contributing to MosaicIQ ## Repository Structure ``` MosaicIQ/ ├── MosaicIQ/ # Main application │ ├── src/ # React + TypeScript frontend │ │ ├── components/ # UI components (Home, Research, Terminal, etc.) │ │ ├── hooks/ # React hooks │ │ ├── lib/ # Shared utilities │ │ ├── news/ # News feed frontend module │ │ ├── research/ # Research workspace frontend module │ │ ├── shared/ # Shared types and helpers │ │ └── types/ # TypeScript type definitions │ ├── src-tauri/ # Rust backend (Tauri 2) │ │ ├── src/ │ │ │ ├── agent/ # AI agent integration (rig-core) │ │ │ ├── commands/ # Tauri command handlers (thin bridge layer) │ │ │ ├── mappings/ # XBRL concept mapping logic │ │ │ ├── news/ # News feed ingestion and storage │ │ │ ├── portfolio/ # Portfolio and quote data │ │ │ ├── research/ # Research workspaces, notes, models │ │ │ ├── terminal/ # Terminal command parsing and routing │ │ │ ├── error.rs # Unified error types │ │ │ ├── state.rs # Shared application state │ │ │ └── lib.rs # Tauri app entry point │ │ └── tests/ # Rust integration tests │ ├── docs/ # Project documentation │ └── public/ # Static assets ├── agent.md # Agent code standards (Rust/backend focus) └── CONTRIBUTING.md # This file ``` ## Tech Stack | Layer | Technology | |---------------|-------------------------------------------------------------------| | Desktop shell | Tauri 2 | | Frontend | React 19, TypeScript 5.8, Vite 7, TailwindCSS 4 | | State | Zustand (client), TanStack Query (server cache) | | Rich text | TipTap | | Charts | Recharts | | Spreadsheets | UniverJS | | Backend | Rust (edition 2021) | | Database | SQLite via rusqlite (bundled) | | HTTP | reqwest | | Data sources | Yahoo Finance (yfinance-rs), RSS/Atom feeds, SEC EDGAR | | AI/Agent | rig-core | | Package mgr | bun (frontend), Cargo (backend) | | Node version | 24.14.1 (see `.nvmrc`) | ## Branch Naming | Pattern | Purpose | |--------------------------------|----------------------------------| | `main` | Production-ready code | | `mvp-X.Y.Z` | Release/milestone branches | | `/` | Feature branches | | `fix/` | Bug fix branches | | `refactor/` | Refactoring branches | Examples: `t3code/expand-inspector-editor`, `fix/news-feed-stale-cache` ## Commit Conventions Use [Conventional Commits](https://www.conventionalcommits.org/) with a short subject line (max 72 chars): ``` (): [optional body] [optional footer(s)] ``` ### Types | Type | When to use | |------------|------------------------------------------------| | `feat` | New feature or user-facing capability | | `fix` | Bug fix | | `refactor` | Code restructuring without behavior change | | `docs` | Documentation only | | `test` | Adding or updating tests | | `chore` | Build, tooling, dependencies, CI | | `perf` | Performance improvement | | `style` | Formatting, whitespace (no logic change) | ### Scopes Use the module or area the change touches: - `terminal` — terminal command parsing/routing - `news` — news feed ingestion, storage, UI - `research` — workspaces, notes, models - `portfolio` — portfolio and quote data - `mappings` — XBRL concept mappings - `agent` — AI agent integration - `ui` — frontend UI components - `state` — app state management - `db` — SQLite schema or migration changes - `build` — build system, Cargo, Vite config Examples: ``` feat(news): add keyword filtering to news feed query fix(terminal): handle empty ticker in lookup command refactor(research): decompose workspace controller into separate hooks docs: add CONTRIBUTING.md with operational guidelines ``` ## Pull Request Flow 1. Create a feature branch from `main` (or the relevant release branch). 2. Make changes in logical commits following the conventions above. 3. Ensure the project compiles and tests pass before requesting review: - Frontend: `bun install && bun run build` - Backend: `cd MosaicIQ/src-tauri && cargo check && cargo test` 4. Open a PR against the target branch with a clear description of what changed and why. 5. At least one approval required before merge. 6. Squash-merge is preferred for feature branches to keep history clean. ## Code Review Expectations - **No dead code** in the active codepath. Remove unused modules, imports, and variables. - **No `unwrap()` or `expect()`** in production Rust code. Use proper error propagation. - **No mock or placeholder logic** in production paths. - **No new public API** without documentation (doc comments for Rust, JSDoc for TypeScript). - **No new stateful logic** without at least focused unit test coverage. - **No structural change** without verifying `cargo check` and `bun run build` both pass. ## Testing ### Rust (Backend) ```bash cd MosaicIQ/src-tauri cargo test # All tests cargo test --lib # Unit tests only cargo test --test # Specific integration test ``` - Every backend behavior change must add or update tests. - Use `test_support.rs` for shared test fixtures. - Use `wiremock` for HTTP mocking, `tempfile` for filesystem isolation. ### TypeScript (Frontend) ```bash cd MosaicIQ bun test ``` - Write tests for hooks, utilities, and data transformations. - Component tests should cover user-facing behavior, not implementation details. ## Secrets and Security - Never commit secrets, API keys, credentials, or tokens to the repository. - API keys (e.g., for remote AI providers) are stored at runtime via the Tauri store plugin, not in code. - Validate all external inputs (API responses, user input, file uploads) before processing. - Sanitize data before storage or display. - Report security concerns to the CTO immediately before merging. ## Architecture Principles These principles guide all technical decisions in this project: 1. **Data freshness vs cost** — Free sources have rate limits. Cache aggressively with clear timestamps. Prefer stale data with indicators over paid real-time feeds. 2. **Separation of concerns** — Data ingestion, processing, storage, and presentation layers must be independently testable and replaceable. 3. **API design as product** — The terminal is API-first. Internal and external interfaces should be clean, documented, and versioned. 4. **Fail gracefully** — If a data source is down, show available data with a clear indicator of what is missing. Never crash on external failures. 5. **Idempotency** — Data ingestion and processing pipelines must be safe to rerun without duplicating data or side effects. 6. **Progressive complexity** — Start with the simplest architecture that solves the problem. Add complexity only when the simple version is proven insufficient. 7. **Observability first** — Log ingestion events, API calls, errors, and data quality metrics from day one. ## Backend Patterns (Rust/Tauri) - Keep Tauri command handlers thin. Business logic belongs in service modules, not command handlers. - Return typed errors from services. Convert to Tauri-compatible errors only at the command boundary. - Keep shared mutable state behind a narrow API. Command handlers must not reach into internal maps directly. - Use conventional Rust module layout (`mod.rs` or flat sibling modules). - Prefer small, composable functions over procedural blocks. ## Frontend Patterns (React/TypeScript) - Use Zustand for global client state. Use TanStack Query for server-derived state. - Components in `src/components/` follow the existing decomposition pattern (screen/workbench/rail). - Custom hooks in `src/hooks/` encapsulate data fetching and state logic. - Shared types in `src/types/`. Do not scatter type definitions across component files. - Use TailwindCSS utility classes. Follow the existing design system conventions.