MosaicIQ/CONTRIBUTING.md

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
<handle>/<short-description>	Feature branches
fix/<short-description>	Bug fix branches
refactor/<short-description>	Refactoring branches

Examples: t3code/expand-inspector-editor, fix/news-feed-stale-cache

Commit Conventions

Use Conventional Commits with a short subject line (max 72 chars):

<type>(<scope>): <description>

[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)

cd MosaicIQ/src-tauri
cargo test                    # All tests
cargo test --lib              # Unit tests only
cargo test --test <name>      # 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)

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.