Development Setup

​

Core Commands

​

Frontend (Next.js)

cd prospero/frontend
npm run dev          # Start development server
npm run build        # Build for production
npm run lint         # Run linting (fails on warnings)
npm run lint:fix     # Fix linting issues
npm run format       # Format with prettier
npm run test         # Run Jest tests
npm run test:e2e     # Run Playwright E2E tests
npm run generate-types # Generate TypeScript types

​

Python (ML/Backend)

cd prospero/python
uv sync                      # Install dependencies
uv run ruff check .          # Run linting
uv run ruff format .         # Format code
uv run mypy .                # Type checking
uv run pytest                # Run all tests
uv run pytest client_tests/  # Integration tests
uv run pytest functional_tests/ # Functional tests

​

Rust (API/Core)

cd prospero/rust
cargo build          # Build all crates
cargo test           # Run tests
cargo clippy         # Run linter
cargo fmt            # Format code
cargo run --bin api  # Run API server

​

Utility Scripts

./scripts/lint.sh             # Lint all components
./scripts/pytests.sh          # Run Python tests
./scripts/client_tests.sh     # Run client integration tests
./scripts/functional_tests.sh # Run functional tests
./scripts/ci_tests.sh         # Run full CI test suite
./scripts/rust_build.sh       # Build Rust components

​

Development Guidelines

​

React/Frontend Best Practices

​

Color System

// Use semantic colors that adapt to theme
<div className="bg-primary text-primary-foreground">
  Primary content
</div>
<div className="bg-error text-error-foreground">
  Error message
</div>

​

Rust Development Standards

​

Code Organization

• Always place use statements at the top of files
• Use workspace dependencies in prospero/rust/Cargo.toml
• Never specify versions in individual crate Cargo.toml files

​

API Development

1. Update the endpoint implementation
2. Run golden tests to update OpenAPI spec:
   Copy

   Ask AI

   cargo test golden  # First run fails
   cargo test golden  # Second run passes
   

3. Update structify.stainless.yml if needed
4. Commit the updated openapi.json

​

Formatting

cargo fmt --all -- --config-path /home/dev/src/prospero/rust/.rustfmt.toml

​

Python Development

​

Workflow Functions

@analytics_decorator()
def process_data(df: pl.LazyFrame) -> pl.LazyFrame:
    # Helper defined inside ensures cache invalidation
    def normalize_value(x):
        return (x - x.mean()) / x.std()

    return df.with_columns(normalize_value(pl.col("value")))

​

API/SDK Generation

1. Source: Rust code with utoipa annotations
2. Generation: Golden tests create openapi.json
3. SDK Creation: Stainless uses OpenAPI + config
4. Distribution: SDKs published to npm/PyPI

​

Critical Rules

​

Code Quality Standards

• Write self-documenting code that doesn’t need comments
• Use clear, descriptive variable names
• Only add comments for genuinely complex logic
• No docstrings or file headers (they become outdated)
• No comments when removing code

​

Git Workflow

• Keep PRs atomic and under ~200 lines when possible
• Use branch naming convention: claude/{feature-name}
• Write clear commit messages focusing on “why”
• Squash and merge to maintain linear history

​

Testing Strategy

​

Test Organization

​

Running Tests

# Run all tests
./scripts/ci_tests.sh

# Component-specific
cd prospero/frontend && npm test
cd prospero/python && uv run pytest
cd prospero/rust && cargo test

​

Environment Setup

​

Required Tools

curl -LsSf https://astral.sh/uv/install.sh | sh

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Using nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18

​

IDE Configuration

​

Startup Mindset

• Speed: Ship features in days, not weeks
• Quality: Maintain high code standards
• Simplicity: Avoid over-engineering
• Focus: Build what users need now