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

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.

4.1 KiB Raw Blame History