Environment Variables

Copy .env.dist to .env and configure the values below.

When running with Docker (make app-run): SERVER__HOST, POSTGRES__HOST, and REDIS__HOST are automatically set to the correct values for the container network - you do not need to change them.

Firebase Setup

Firebase is used for sending push notifications to mobile devices (FCM).

1. Generate a service account key

1. Open the Firebase Console and select your project
2. Go to Project Settings → Service accounts
3. Click Generate new private key → Generate key
4. A .json file will download — this is your credentials file

2. Configure the app

Place the downloaded file in the project root (or any path you prefer) and set the following in .env:

FIREBASE__CREDENTIALS_PATH=firebase-creds.json
FIREBASE__PROJECT_ID=your-firebase-project-id

The path is resolved from the working directory where the server is launched (the project root when using make run).

Important: Add the credentials file to .gitignore — never commit it to version control.

Make Commands

make install           # Install Python dependencies via Poetry
make install-hooks     # Install pre-commit git hooks

make run               # Start dev server locally (requires running services)
make app-run           # Start full stack via Docker (app + db + redis)
make app-run-services  # Start PostgreSQL + Redis only via Docker
make down              # Stop all Docker services
make logs              # Follow app container logs

make migrate           # Apply pending Alembic migrations
make migration message="describe change"  # Autogenerate a new migration
make db-reset          # Drop and recreate public schema, then apply all migrations

make lint              # Check code style (ruff)
make reformat          # Auto-fix and format code (ruff)

make tests             # Run full test suite (starts services automatically)

Running Tests

# Run full suite
make tests

# Run a specific test file or case
poetry run pytest tests/auth/test_auth.py -v
poetry run pytest tests/auth/test_auth.py::test_login -v

Tests use an in-memory SQLite database - no running PostgreSQL required.

Testing Stripe Locally

Stripe webhooks require a publicly accessible URL. In development, use the Stripe CLI to forward events to your local server.

1. Install Stripe CLI

# macOS
brew install stripe/stripe-cli/stripe

# Windows and others
Check the official installation guide: https://stripe.com/docs/stripe-cli#install

2. Authenticate

stripe login

This opens a browser to authorize the CLI against your Stripe account.

3. Forward webhooks to your local server

stripe listen --forward-to localhost:8080/api/payments/webhooks/stripe

The CLI prints a webhook signing secret on startup:

> Ready! Your webhook signing secret is whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Copy that value and set it in .env:

STRIPE__WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Restart the dev server after updating .env. Keep the stripe listen process running in a separate terminal - it must stay alive to receive forwarded events.

4. Set your Stripe test secret key

In the Stripe Dashboard, copy the Secret key from the test environment (sk_test_...) and set:

STRIPE__SECRET_KEY=sk_test_...
STRIPE__SUCCESS_URL=http://localhost:3000/payment/success
STRIPE__CANCEL_URL=http://localhost:3000/payment/cancel

5. Test the full checkout flow

Step 1 - Create a checkout session via the API:

curl -X POST http://localhost:8080/api/payments/checkout \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000}'

The response contains a checkout_url. Open it in the browser and complete the payment using Stripe's test card:

After completing the payment, Stripe sends a checkout.session.completed event to the CLI, which forwards it to your server. The user's balance is updated automatically.

6. Trigger events manually (without UI)

# Simulate a completed payment
stripe trigger checkout.session.completed

# Simulate an expired session
stripe trigger checkout.session.expired

Note: Manually triggered events use Stripe-generated test data and will not match sessions created via your API. Use them only to verify webhook handler logic in isolation.

Project Structure

src/
├── app.py                  # FastAPI application factory
├── lifetime.py             # Startup/shutdown lifespan events
├── core/
│   ├── config/             # Pydantic settings (loaded via get_config())
│   ├── database/           # BaseRepository, UnitOfWork, session factory
│   ├── dependencies.py     # FastAPI Depends() providers
│   ├── exceptions.py       # Base domain error hierarchy
│   └── security/           # JWT and password hashing utilities
└── domains/
    ├── auth/               # Login, logout, token refresh
    ├── users/              # User profiles
    ├── categories/         # Product category tree
    ├── filter_definitions/ # Per-category custom filter schemas
    ├── listings/           # Marketplace listings
    ├── images/             # Image upload and storage (S3)
    ├── favourites/         # User favourites
    ├── promotions/         # Promotion packets and listing promotions
    ├── payments/           # Stripe checkout, webhooks, balance transactions
    └── chat/               # Conversations, messages, WebSocket real-time layer

Each domain follows the pattern: model.py → repository.py → service.py → router.py.

API

All routes are prefixed with /api:

With SERVER__DEBUG=true, interactive docs are available at:

• Swagger UI: http://localhost:8080/api/docs
• ReDoc: http://localhost:8080/api/redoc

Chat

The chat system uses REST for conversation and message management and WebSockets for real-time delivery.

Key REST endpoints:

Every ConversationResponse includes an unread_count field. Messages are marked as read when the user connects via WebSocket or fetches message history via REST; a messages_read event is broadcast to the conversation channel so the other participant can update their UI in real time.

See docs/chat-websocket.md for the full WebSocket protocol reference.