Development Setup

Prerequisites

Tool	Version	Purpose
Rust	stable 1.80+	Backend
Node.js + Bun	latest	Frontend
PostgreSQL	15+	Database
NATS	optional	Event transport (federation + notifications)
Docker + Docker Compose	optional	Run deps in containers

Backend

# Copy and fill in env
cp .env.example .env

# Start the API server (runs migrations automatically on startup)
cargo run -p bootstrap

# In a second terminal: start the event worker (optional)
cargo run -p worker

The API server starts on http://localhost:8000.
Both processes read from the same .env file.

Environment Variables (`.env.example`)

DATABASE_URL=postgres://postgres:password@localhost:5432/thoughts
JWT_SECRET=change-me
BASE_URL=http://localhost:8000
NATS_URL=nats://localhost:4222   # optional

BASE_URL is used to construct ActivityPub actor URLs and AP object IDs — must be the publicly reachable URL in production.

Running Tests

# Unit tests — no database required
cargo test -p application

# Full workspace (requires DATABASE_URL pointing to a running PostgreSQL)
cargo test --workspace

The application crate uses in-memory fakes from domain's test-helpers feature for fast, isolated unit tests of all business logic.

Frontend

cd thoughts-frontend

# Install dependencies
bun install

# Start dev server
bun run dev   # http://localhost:3000

Environment Variables (`thoughts-frontend/.env.example`)

NEXT_PUBLIC_API_URL=http://localhost:8000          # client-side requests
NEXT_PUBLIC_SERVER_SIDE_API_URL=http://localhost:8000  # SSR requests

Running Everything with Docker Compose

# Start all services (api, worker, frontend, postgres, nats, nginx)
docker compose up

# Or just the database
docker compose up database

# Or database + NATS only
docker compose up database nats

compose.yml at the repo root defines all services for local development.

Project Structure

thoughts/
├── Cargo.toml             # Workspace root
├── .env.example           # Backend env template
├── compose.yml            # Dev Docker Compose
├── compose.prod.yml       # Production Docker Compose
├── Dockerfile             # Multi-stage build (api + worker binaries)
├── nginx/
├── crates/
│   ├── domain/            # Pure domain types & port traits
│   ├── application/       # Use cases (business logic)
│   ├── api-types/         # REST request/response DTOs
│   ├── presentation/      # Axum HTTP router, OpenAPI
│   ├── bootstrap/         # API server binary
│   ├── worker/            # Event worker binary
│   └── adapters/
│       ├── auth/
│       ├── postgres/      # SQL repos + migrations/
│       ├── postgres-search/
│       ├── postgres-federation/
│       ├── activitypub-base/
│       ├── activitypub/
│       ├── nats/
│       ├── event-payload/
│       └── event-transport/
└── thoughts-frontend/     # Next.js frontend
    ├── app/               # App Router pages
    ├── components/        # React components (incl. federation/)
    ├── hooks/
    └── lib/               # API client, utils