web-hosts/domains/coppertone.tech/docs/api/README.md

# Coppertone.tech API Documentation

## Overview

This documentation covers all backend microservices for the Coppertone.tech platform.

## Services

| Service | Port | Description | Documentation |
|---------|------|-------------|---------------|
| **auth-service** | 8082 | Authentication, authorization, user management | [auth-service.md](./auth-service.md) |
| **work-management-service** | 8083 | Projects, tasks, work orders | [work-management-service.md](./work-management-service.md) |
| **payment-service** | 8084 | Invoices, payments, Stripe integration | [payment-service.md](./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

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

Response:
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Using the Token

Include the token in all subsequent requests:

```bash
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

```json
{
  "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

```json
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

```bash
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

```bash
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

```bash
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)

```bash
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

```bash
# 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

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

## Security Notes

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