battlechores-server

BattleChores is a self-hosted household chore RPG with:

• PostgreSQL database
• FastAPI backend API
• Responsive web client (for current development/testing)

The web app is the primary client for now, with Android planned later.

Prerequisites

• Docker
• Docker Compose (v2)
• Poetry (optional for local non-Docker development)

Quick start

1. Copy environment variables:

   cp .env.example .env
   

2. Build and start the stack:

   docker compose up --build
   

3. Open:

   • Web client: http://localhost:3000/
   • API root: http://localhost:8000/
   • API docs: http://localhost:8000/docs
   • API db health: http://localhost:8000/db-health

Services

• web - Nginx-served responsive test client.
• api - FastAPI app running with hot reload and Poetry.
• db - PostgreSQL 16 with persisted volume postgres_data.

Poetry commands (local API development)

Install dependencies:

poetry install

Run API locally:

poetry run uvicorn app.main:app --reload

Run migrations:

poetry run alembic upgrade head

Create a new migration after model changes:

poetry run alembic revision --autogenerate -m "describe change"

Chore admin and users

Self-hosted installs define a single chore admin (GM) in .env:

• CHORE_ADMIN_USERNAME — only this user can create new family groups (POST /households).
• CHORE_ADMIN_PASSWORD — password; on each API startup the admin row in the database is updated to match these values.

There is no public registration. The admin logs in, then:

1. POST /admin/users — create accounts for family members (username/password).
2. POST /households — create a family group (admin becomes owner).
3. POST /households/{household_id}/members — add those users with roles (parent, family_member, etc.).

Initial API endpoints

• POST /auth/login -> login and return bearer token
• POST /admin/users -> chore admin creates a family user account
• POST /households -> chore admin creates a family group (owner role)
• POST /households/{household_id}/members -> owner/parent can add member with role
• POST /chores -> owner/parent creates chore
• GET /households/{household_id}/chores -> list chores for a household member
• POST /chore-completions -> member submits chore completion
• POST /chore-completions/{completion_id}/review -> owner/parent approves/rejects, approval grants XP

Use Authorization: Bearer <token> for protected routes.

Development notes

• App code lives in app/.

• API routes are split into app/routes/ modules.

• SQLAlchemy models are in app/models.py.

• Alembic migrations live in alembic/versions/.

• Web client code lives in web/.

• Default PostgreSQL host for containerized app is db.

• Stop stack:

  docker compose down
  

• Stop and remove volumes:

  docker compose down -v
  

Early domain model (suggested)

Start with these core entities:

• User with role: owner, parent, family_member
• Household and membership table
• Chore with XP reward, optional item reward
• ChoreCompletion requiring manager/admin approval
• Character with level, XP, basic stats
• InventoryItem and optional item grants

Suggested first gameplay loop:

1. Admin/Manager creates chore
2. Family member marks complete
3. Admin/Manager approves completion
4. XP and items are granted to character
5. Character can level up when XP threshold is met