torus-api/GROK.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

cargo build          # compile
cargo run            # run the server (reads .env automatically)
cargo test           # run all tests
cargo test <name>    # run a single test by name
cargo clippy         # lint
cargo fmt            # format

Architecture

Single-binary Actix Web API. Entry point is src/main.rs, which:

1. Loads .env via dotenvy at startup
2. Reads APP_ENV (development | production) and PORT from the environment
3. Binds to 127.0.0.1:<PORT> in development, example.com:<PORT> in production
4. Registers all routes on the HttpServer

Routes are registered as Actix handler functions decorated with #[get(...)] / #[post(...)] etc. and passed to App::new().service(...). As the API grows, handlers should be split into modules under src/ and re-exported for registration in main.

Environment

.env is read at runtime (not compile time). Required variables:

Variable	Description
APP_ENV	development or production
PORT	numeric port, e.g. 8000
DATABASE_URL	Postgres connection string, e.g. postgres://user:password@localhost/torus
JWT_SECRET	Secret key used to sign and verify JWTs

Rules

1. Do not build the program after finishing a task
2. Do not run redocly to build the docs
3. Any time that a route is created or changed, update the docs as well
4. Make sure that any errors that are ever created contain and send to the front-end a good, brief description that can just be printed for the user by the front-end