fd9af24e22
- Add BACKEND_SECURITY.md with security analysis and hardening guide - Add FRONTEND_TESTING_STRATEGY.md with test coverage strategy - Update API.md with new endpoints (candidates, tickets, credentials) - Update AGENTS.md documentation index
105 lines
5.2 KiB
Markdown
105 lines
5.2 KiB
Markdown
# 🔌 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`).
|
|
|
|
### Candidates (Admin)
|
|
* `GET /candidates`: Lists all candidates with pagination (`?page=1&perPage=10`). Returns stats and pagination metadata.
|
|
|
|
### Tickets & Support (Backend)
|
|
* `POST /support/tickets`: Creates a support ticket. Requires `{ subject, category, priority, message }`. Categories: `bug`, `feature`, `support`, `billing`, `other`.
|
|
* `GET /support/tickets`: Lists user's tickets.
|
|
* `GET /support/tickets/{id}`: Get ticket details with messages.
|
|
* `POST /support/tickets/{id}/messages`: Add message to ticket.
|
|
* `POST /support/tickets/{id}/close`: Close ticket.
|
|
|
|
### Settings & Credentials
|
|
* `GET /settings/{key}`: Get settings by key (e.g., `theme`).
|
|
* `POST /settings/{key}`: Save settings.
|
|
* `GET /credentials`: List configured external services.
|
|
* `POST /credentials/{service}`: Save credentials for a service.
|
|
* `DELETE /credentials/{service}`: Delete credentials.
|
|
* **Supported Services:** `stripe`, `storage` (S3), `cloudflare_config`, `cpanel`, `lavinmq`, `appwrite`, `fcm_service_account`, `smtp`.
|
|
|
|
### 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.
|