Service	Port	Description	Documentation
auth-service	8082	Authentication, authorization, user management	auth-service.md
work-management-service	8083	Projects, tasks, work orders	work-management-service.md
payment-service	8084	Invoices, payments, Stripe integration	payment-service.md

Authentication

All services use JWT-based authentication. Tokens are issued by the auth-service and validated by all other services.

Obtaining a Token

curl -X POST http://localhost:8082/login-email-password \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "SecurePass123"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Using the Token

Include the token in all subsequent requests:

curl http://localhost:8083/projects \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Role Hierarchy

The platform uses a hierarchical role-based access control (RBAC) system:

SUPERUSER (Level 4 - God Mode)
    │
    ├── Can do everything
    ├── Can promote/demote other SUPERUSERs
    └── Initial SUPERUSER cannot be deleted (can only transfer)

ADMIN (Level 3)
    │
    ├── Full access to all resources
    ├── Can manage STAFF and CLIENT users
    └── Cannot touch SUPERUSER accounts

STAFF (Level 2)
    │
    ├── Create/manage projects, tasks, work orders
    ├── Create/manage invoices and payments
    └── Limited user management

CLIENT (Level 1)
    │
    ├── View own projects and tasks
    ├── View own invoices
    ├── Make payments
    └── Request new projects

Special Roles

Role	Description
SUPERUSER	God-like permissions, full system access
Initial SUPERUSER	First user created. Cannot be deleted, can only transfer status

Common Response Formats

Success Response

{
  "id": 1,
  "name": "Resource Name",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Error Response

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Error message here

Validation Error

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "field": "email",
  "message": "Invalid email format"
}

HTTP Status Codes

Code	Meaning
200	OK - Request succeeded
201	Created - Resource created successfully
204	No Content - Successful deletion
400	Bad Request - Invalid input
401	Unauthorized - Missing or invalid token
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
409	Conflict - Duplicate resource
500	Internal Server Error - Server-side error
503	Service Unavailable - Feature not configured

Environment Variables

All services share common environment variables:

Variable	Required	Description
`JWT_SECRET`	Yes	JWT signing key (min 32 chars)
`DB_HOST`	Yes	PostgreSQL host
`DB_USER`	Yes	PostgreSQL username
`DB_PASSWORD`	Yes	PostgreSQL password
`DB_NAME`	Yes	PostgreSQL database name
`DB_SSL_MODE`	No	SSL mode (default: `require`)
`DB_SCHEMA`	No	Schema (dev/testing/prod)
`CORS_ALLOW_ORIGIN`	No	CORS origin (default: `http://localhost:8090`)

Service-Specific Variables

payment-service:

STRIPE_SECRET_KEY - Stripe API secret key
STRIPE_WEBHOOK_SECRET - Stripe webhook signing secret

Quick Start Examples

Register a New User

curl -X POST http://localhost:8082/register-email-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "SecurePass123",
    "name": "New User"
  }'

Create a Project

curl -X POST http://localhost:8083/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "New Project",
    "description": "Project description",
    "clientId": 5
  }'

Create an Invoice

curl -X POST http://localhost:8084/invoices \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "invoiceNumber": "INV-2024-001",
    "clientId": 5,
    "amount": 5000.00,
    "currency": "USD"
  }'

Pay an Invoice (Stripe)

curl -X POST http://localhost:8084/invoices/create-payment-intent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"invoiceId": 1}'

Development

Running Locally

# Start all services
podman-compose up -d

# Check service health
curl http://localhost:8082/healthz  # auth-service
curl http://localhost:8083/healthz  # work-management-service
curl http://localhost:8084/healthz  # payment-service

Database Migrations

# Run migrations
cd backend/migrations
for f in *.up.sql; do psql -U user -d coppertone_db -f "$f"; done

Security Notes

Never expose JWT_SECRET - Use environment variables or secrets management
Use HTTPS in production - All traffic should be encrypted
Rotate JWT tokens - Tokens expire after 24 hours
Validate webhook signatures - Stripe webhooks are signature-verified
PAID invoices are immutable - Cannot be modified or deleted for audit compliance