gohorsejobs/docs/API.md

🔌 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:

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.