Repository Guidelines

Project Structure & Module Organization

crates/: Rust workspace crates — server (API + bins), db (SQLx models/migrations), executors, services, utils, deployment, local-deployment.
frontend/: React + TypeScript app (Vite, Tailwind). Source in frontend/src.
shared/: Generated TypeScript types (shared/types.ts). Do not edit directly.
assets/, dev_assets_seed/, dev_assets/: Packaged and local dev assets.
npx-cli/: Files published to the npm CLI package.
scripts/: Dev helpers (ports, DB preparation).

Managing Shared Types Between Rust and TypeScript

ts-rs allows you to derive TypeScript types from Rust structs/enums. By annotating your Rust types with #[derive(TS)] and related macros, ts-rs will generate .ts declaration files for those types. When making changes to the types, you can regenerate them using npm run generate-types Do not manually edit shared/types.ts, instead edit crates/server/src/bin/generate_types.rs

Build, Test, and Development Commands

Install: pnpm i
Run dev (frontend + backend with ports auto-assigned): pnpm run dev
Backend (watch): npm run backend:dev:watch
Frontend (dev): npm run frontend:dev
Type checks: npm run check (frontend) and npm run backend:check (Rust cargo check)
Rust tests: cargo test --workspace
Generate TS types from Rust: npm run generate-types (or generate-types:check in CI)
Prepare SQLx (offline): npm run prepare-db
Local NPX build: npm run build:npx then npm pack in npx-cli/

Coding Style & Naming Conventions

Rust: rustfmt enforced (rustfmt.toml); group imports by crate; snake_case modules, PascalCase types.
TypeScript/React: ESLint + Prettier (2 spaces, single quotes, 80 cols). PascalCase components, camelCase vars/functions, kebab-case file names where practical.
Keep functions small, add Debug/Serialize/Deserialize where useful.

Testing Guidelines

Rust: prefer unit tests alongside code (#[cfg(test)]), run cargo test --workspace. Add tests for new logic and edge cases.
Frontend: ensure npm run check and npm run lint pass. If adding runtime logic, include lightweight tests (e.g., Vitest) in the same directory.

Security & Config Tips

Use .env for local overrides; never commit secrets. Key envs: FRONTEND_PORT, BACKEND_PORT, HOST, optional GITHUB_CLIENT_ID for custom OAuth.
Dev ports and assets are managed by scripts/setup-dev-environment.js.

2.4 KiB Raw Blame History