Contributing

Prerequisites

• macOS 12+ (Tauri builds target macOS)
• Bun (runtime for the server)
• Node.js 22+ (for frontend tooling)
• Rust (for Tauri native shell)

Clone and install

git clone https://github.com/aballiet/retrace.git
cd retrace
bun install

Development

Start the API server and frontend in development mode:

# Terminal 1: API server
cd packages/server
bun run dev

# Terminal 2: Frontend
cd packages/app
bun run dev

The frontend runs on localhost:1420 with hot reload. The API server restarts on file changes.

Project layout

packages/
  app/                React frontend (Vite + React Router)
    src/
      pages/          Route pages
      components/     UI components
  server/             Bun API server (Hono)
    src/
      routes/         API route handlers
      consumers/      MCP server, ingest pipeline
      db/             Drizzle schema + migrations

Database migrations

Retrace uses Drizzle ORM for schema management:

cd packages/server
bun run db:generate    # Generate migration from schema changes
bun run db:migrate     # Apply pending migrations

Adding a new import source

1. Create a parser in packages/server/src/parsers/
2. Add the platform to the unified import route in routes/import-unified.ts
3. Add a card in the frontend import UI
4. Write a docs page in retrace-site/docs/content/docs/import/

Running tests

bun test

Code style

• TypeScript throughout (server + frontend)
• Functional components with hooks (React)
• Hono route handlers return JSON
• Drizzle for all database queries (no raw SQL)

Submitting changes

1. Fork the repo and create a branch
2. Make your changes
3. Run tests
4. Open a pull request against main

See GitHub Issues for things to work on.