# 🔌 API Documentation & Routing - GoHorseJobs

This document outlines the API landscape across the GoHorseJobs monorepo, detailing the main services and how they communicate.

---

## 🏗️ API Architecture & Communication

*   **Backend API (Go):** The central source of truth for the platform. Handles all core business logic (Users, Companies, Jobs, Applications).
*   **Backoffice API (NestJS):** Dedicated to administrative tasks, workers (email queues), and specialized integrations (Stripe, Firebase Cloud Messaging). Shares the **same PostgreSQL database** as the Backend API.
*   **Seeder API (Node.js):** Runs strictly on demand to populate the database with dummy data or run migrations.

### Communication Flow (Frontend)
The Next.js Frontend primarily communicates with the **Backend API**.
*   **Paradigm:** The frontend uses React Server Components (RSC) to fetch data natively from the Go API.
*   **Client Actions:** For forms and interactivity (e.g., login, apply), client components dispatch requests using the wrapped fetch utility located at `src/lib/api.ts`.
*   **Auth State:** JWT tokens are stored locally (Cookies/Storage) and appended to the `Authorization: Bearer <token>` header manually via interceptors or utility functions.

---

## 📡 Backend API Reference (`/api/v1`)
Hosted at `api-local.gohorsejobs.com` (Dev) or `api.gohorsejobs.com` (Prd).
View detailed interactive Swagger Docs by visiting `/swagger/index.html`.

### Authentication
*   `POST /auth/login`: Accepts `{ "email": "...", "password": "..."}`. Returns JWT token and User DTO.
*   `POST /auth/register/candidate`: Creates a standard user.
*   `POST /auth/register/company`: Creates a user and a linked `Company` profile awaiting approval.

### Users & Profiles
*   `GET /users/me`: Gets the full profile of the currently authenticated user (derived from JWT context).
*   `PUT /users/me`: Updates profile details.
*   `GET /admin/users`: (Admin only) Lists all users.

### Companies
*   `GET /companies`: Lists active companies with pagination and filters.
*   `GET /companies/{id}`: Detailed company view.
*   `PUT /companies/{id}`: Edit company profile (Requires owner/admin permissions via `user_companies` relation).
*   `POST /admin/companies/{id}/status`: (Admin only) Approve/Reject pending companies.

### Jobs & Applications
*   `GET /jobs`: Lists published jobs. (Supports full-text search and filters).
*   `POST /jobs`: Creates a draft job (Requires Recruiter).
*   `PUT /jobs/{id}`: Updates job details.
*   `POST /jobs/{id}/apply`: Submits an application for the job.
*   `GET /applications`: Lists received applications (for recruiters) or submitted applications (for candidates).
*   `POST /applications/{id}/status`: Updates application status (`reviewing`, `accepted`, `rejected`).

### Miscellaneous
*   `GET /health`: Basic ping endpoint.
*   `POST /storage/upload-url`: Requests a presigned URL (S3/Cloudflare R2) to upload logos or resumes directly from the browser.

---

## 🛠️ Backoffice API Reference (`/api`)
Hosted at `b-local.gohorsejobs.com` (Dev) or `b.gohorsejobs.com` (Prd).
View detailed interactive Swagger Docs by visiting `/api/docs`.

### Tickets & Support
*   `POST /tickets`: Public endpoint (no auth required) to submit a contact/support ticket. Used directly by the frontend `/contact` page.
*   `GET /tickets`: (Admin only) Lists all open tickets.
*   `POST /tickets/{id}/reply`: (Admin only) Adds a message to a ticket and triggers an email notification to the user.

### Emails & Workers
The Backoffice listens to a LavinMQ (AMQP) message queue to dispatch transactional emails (welcome, password reset, application updates) securely without blocking the main Go runtime.

### Stripe Billing
*   `POST /stripe/webhook`: Consumes Stripe events to upgrade company plans from Free to Pro/Enterprise.

---

## 📚 Seeder API Commands

If you need to instantly provision the database for these routes to work:

```bash
cd seeder-api
npm install

# Drops all tables, runs migrations, inserts core test users (100 jobs, 50 companies)
npm run seed:lite 

# Runs migrations ONLY
npm run migrate
``` 

The seeder automatically inserts the `Admin@2025!` superadmin hash required for local testing.