# Gem Track Backend - API Documentation Overview

Welcome to the backend API reference for **Gem Track**! This guide is designed to help frontend developers and API integrators understand the available resources, authentication flow, and how to start making requests locally.

## Detailed OpenAPI Reference

The backend uses **TSOA**, which means that our API routes and schemas are strongly-typed and automatically generated. 

You can access the full Interactive Swagger API documentation by navigating to:
👉 **[http://localhost:3000/docs](http://localhost:3000/docs)** 

*(Make sure you have started your Docker environment via `docker compose up` first)*

From the Swagger UI, you can:
- **Test Endpoints**: Execute API requests directly from your browser.
- **View Schemas**: Inspect the exact JSON payload shapes for requests and responses.
- **Download Specification**: Grab the raw `swagger.json` file to auto-generate frontend SDKs/clients using generic tools (like OpenAPI Generator or Orval).

---

## High-Level Capabilities

The API exposes endpoints divided into distinct domains:

### 1. Tenancy (`/api/v1/tenants`)
Gem Track is a multi-tenant application. Every organization runs in its own tenant container.
- **`POST /api/v1/tenants`**: Onboard a new tenant (this sets up default DB rows, billing plans, roles, and permissions).
- **`GET /api/v1/tenants/{tenantId}`**: Fetch details about an active tenant.

### 2. Authentication (`/api/v1/auth`)
Tokens are issued via JWT and must be provided natively in the `Authorization` header (`Bearer <token>`).
- **`POST /api/v1/auth/register`**: Enroll the first administrator user for a new tenant.
- **`POST /api/v1/auth/login`**: Acquire a JWT credential by authenticating.
- **`GET /api/v1/auth/me`**: Returns profile info, active roles, and authorization scopes (permissions) for the current user.

### 3. User Management (`/api/v1/users`)
- **`POST /api/v1/users`**: Directly create a new user profile inside a tenant.
- **`POST /api/v1/users/invite`**: Issue an invitation to a new team member.
- **`PATCH /api/v1/users/{userId}/roles`**: Assign operational security roles (`tenant_admin` or `tenant_user`).
- **`PATCH /api/v1/users/{userId}/status`**: Adjust user standing (active/suspended).
- **`GET /api/v1/users/{userId}`**: Extract scoped profile details.

### 4. Billing (`/api/v1/billing`)
Tracks the assigned tier usage context logic.
- **`GET /api/v1/billing/subscription`**: Pull the current subscription parameters (e.g., Free vs Pro vs Enterprise limits).
- **`POST /api/v1/billing/subscription/plan`**: Downgrade/Upgrade the overarching plan context constraints.
- **`GET /api/v1/billing/history`**: Return paginated historical statement data.

### 5. Task Management (`/api/v1/tasks`)
Agile tracking mechanics for users operating within the ecosystem.
- **`POST /api/v1/tasks`**: Map a new task context.
- **`GET /api/v1/tasks`**: Read parameters, scope visibility based on user tenant constraints.
- **`PATCH /api/v1/tasks/{taskId}` & Sub-Tasks**: Mutate progress milestones spanning assignments.

### 6. Document Management (`/api/v1/documents`)
- **`POST /api/v1/documents`**: Implements multi-part form data uploads for handling physical file ingest scaling.
- **`GET /api/v1/documents`**: Retrieves associated files stored alongside records.

---

## Common Workflows

### System Setup
1. **Create the Tenant**: Hit `POST /api/v1/tenants`
2. **Create the Admin User**: Hit `POST /api/v1/auth/register` using the UUID returned from step 1.
3. **Login in App**: Send credentials via `POST /api/v1/auth/login` and persist the generated `accessToken`.

### Authenticating Requests
Once you have the `accessToken` from login, all requests tagged with the lock icon in Swagger (which require the `bearerAuth` security schema) must include the following header:

```http
Authorization: Bearer <your-access-token>
```