rhythm-backend/README.md

Rhythm Backend (Go)

Lean Go API backend for ISeeU Tracker.

Current Project State

• Go module initialized (go.mod)
• Entry point created (cmd/api/main.go)
• Env config package created (internal/config/config.go)
• .env loading added with required DB variables
• Local Postgres service available in compose.yaml (dev profile)
• Database connection package (internal/db) not implemented yet
• Goose migrations folder/files not created yet
• HTTP router and handlers not implemented yet
• User DTO/model/repository/service not implemented yet

General Folder Structure

cmd/
  api/
    main.go                 # application entrypoint

internal/
  config/                   # env and app config
  db/                       # postgres/sqlx connection + migrations
  http/                     # router, middleware, handlers
  auth/                     # jwt, password hashing, auth middleware
  service/                  # business logic
  repository/               # SQLx queries (no ORM)
  model/                    # domain models + request/response DTOs

migrations/                 # Goose SQL migrations
scripts/                    # optional local/dev scripts

Roadmap Checklist (Do Not Delete)

Chapter 1 - Bootstrap and Config

• Create cmd/api/main.go
• Create internal/config package
• Load .env and validate required DB env vars
• Add APP_PORT env var with default fallback
• Improve startup logs (without printing secrets)

Chapter 2 - Database and Goose

• Add internal/db/postgres.go with sqlx connection
• Add internal/db/migrate.go to run Goose at startup
• Create migrations/ directory
• Create first migration for users table
• Wire migration call into app startup (before HTTP server)
• Add goose status and rollback notes in README

Chapter 3 - User Vertical Slice (First Feature)

• Add user DTO (username, password) in internal/model
• Add user DB model (id, username, password_hash, timestamps)
• Add user repository with SQLx (CreateUser, GetByUsername)
• Add user service with bcrypt hashing
• Add POST /users/register handler
• Add input validation and proper error responses

Chapter 4 - HTTP Layer and Health

• Add router setup in internal/http/router.go
• Add GET /health endpoint
• Add JSON response helpers
• Add request logging middleware
• Add panic recovery middleware

Chapter 5 - Security Foundation

• Add password hashing and compare helpers
• Add JWT generation/verification package
• Add auth middleware for protected routes
• Add POST /auth/login
• Add GET /auth/me

Chapter 6 - Developer Experience

• Add Makefile targets (run, db-up, migrate-up, migrate-down)
• Add graceful shutdown in main.go
• Add structured logging (log/slog)
• Add .env.example updates for all required vars
• Add basic project usage section in README

Chapter 7 - Testing

• Add unit tests for config package
• Add unit tests for user service
• Add repository integration test setup (test DB)
• Add handler tests for register endpoint
• Add CI step to run tests

Notes

• Keep handlers thin, business logic in service, SQL in repository.
• Use sqlx for explicit SQL and scan helpers.
• Use goose for schema versioning and run migrations automatically at startup.
• Never store plain passwords; always use password_hash.