# AGENTS.md - GoHorse Jobs

> **Purpose:** Context and Directives for AI coding assistants (Claude, Cursor, Aider, etc.)
> **Branch Context:** `dev`

---

## 🚨 SUPERIOR DIRECTIVES 🚨

1. **DO NOT TOUCH KUBERNETES/SECRETS**: You are strictly forbidden from modifying any files in `k8s/` or altering raw RSA/base64 authentication keys.
2. **ENV VARIABLES**: Never hardcode secrets in code. If you define a new environment variable, it must be documented. Next.js variables exposed to the client must use the `NEXT_PUBLIC_` prefix. NEVER expose secrets with `NEXT_PUBLIC_`.
3. **READ FIRST**: Before implementing new features, always read the relevant documentation in this `docs/` folder to understand existing patterns (e.g., Go Clean Architecture, React Server Components).

---

## Project Overview

GoHorse Jobs is a modern B2B SaaS recruitment platform connecting companies with candidates. It operates across multiple services sharing a single PostgreSQL database.

**Business model**: Freemium (Free / Pro R$199/month / Enterprise custom pricing).

### Repository Structure

```text
gohorsejobs/
├── backend/              # Go REST API (Clean Architecture + DDD)
├── frontend/             # Next.js web application (App Router)
├── backoffice/           # NestJS admin and worker API
├── seeder-api/           # Node.js Express database seeder
├── job-scraper-multisite/# Job scraping service
├── k8s/                  # Kubernetes manifests (FORBIDDEN DOMAIN)
├── docs/                 # Central documentation
├── .forgejo/             # Forgejo actions workflows
└── start.sh              # Interactive dev startup script
```

---

## Architecture & Conventions

### Backend (Go 1.24)
*   **Architecture**: Clean Architecture + Domain Driven Design (DDD)
*   **Flow**: Controller (`internal/handlers`) -> UseCase (`internal/core/usecases`) -> Interface Port (`internal/core/ports`) -> Repository (`internal/infrastructure/persistence`).
*   **Key Libs**: `net/http` (stdlib routing), `lib/pq` + `gorm` (legacy/transitioning), `swaggo` (Docs).
*   **Running**: `cd backend && go run cmd/api/main.go` (Port 8521)

### Frontend (Next.js 15)
*   **Architecture**: App Router (`src/app`), heavily favoring React Server Components (RSC). Use `'use client'` strictly at the leaf nodes of the component tree for interactivity.
*   **Styling**: Tailwind CSS, generic UI components in `src/components/ui` (shadcn).
*   **State & Validation**: Zustand (global state), React Hook Form + Zod (forms).
*   **i18n**: Multi-language support (PT, EN, ES, JA). Ensure all text is extracted to translation files.
*   **Running**: `cd frontend && npm run dev -p 8963` (Port 8963)

### Backoffice (NestJS 11)
*   **Architecture**: Modular NestJS over Fastify.
*   **Modules**: Admin, Auth, Email (Worker), Stripe, Tickets.
*   **Running**: `cd backoffice && npm run start:dev` (Port 3001)

### Seeder API (Express 5)
*   **Purpose**: Manages database migrations and test data populations.
*   **Running**: `cd seeder-api && npm run seed`

---

## ⚠️ Known Gotchas & Historical Errors

### 1. The `PASSWORD_PEPPER` Trap
**Symptom**: "Invalid credentials" upon login right after seeding the database.
**Cause**: The initial SQL migration creates the superadmin, but lacks the bcrypt pepper hashing. The Node.js `seeder-api` calculates the real hash.
**Fix**: You must run `npm run migrate` **AND THEN** `npm run seed` in the `seeder-api` directory. The seeder will read `PASSWORD_PEPPER` (e.g., `gohorse-pepper`) from your `.env` and fix the hashes.

### 2. Login Payload
The frontend login form sends `{ "email": "admin", "password": "..." }`. The backend resolves this against the `email` or `identifier` columns. **Do not** change the payload payload to `{ "identifier": "admin" }` because the backend DTO explicitly expects the JSON key `"email"`.

### 3. Bcrypt in bash strings
**Never** run a raw SQL command via bash `docker exec` containing a bcrypt hash like `$2b$10$...`. The bash shell expands `$2b` as a variable, corrupting the hash. Always write the SQL to a file and execute the file.

### 4. Contact/Tickets
The contact form uses Next.js internationalization and routes directly to the backoffice `tickets` API. Emails go to `wtf@gohorsejobs.com`.

---

## Dev Environments & Test Users

**Environments**:
*   **dev**: Current working branch. Deployed to `dev.gohorsejobs.com` or `local.gohorsejobs.com`
*   **main**: Production branch.

**Test Users** (Local/Dev):
*   Superadmin: `lol` / `Admin@2025!`
*   Superadmin: `superadmin` / `Admin@2025!`

See [docs/TEST_USERS.md](TEST_USERS.md) for Candidate and Company personas.

## Documentation Index

When asked to learn or modify parts of the system, consult these files first:
*   [API.md](API.md) - Endpoint contracts
*   [API_SECURITY.md](API_SECURITY.md) - Auth, RBAC
*   [APPSEC_STRATEGY.md](APPSEC_STRATEGY.md) - Application Security and Testing
*   [BACKEND_SECURITY.md](BACKEND_SECURITY.md) - Backend Security Analysis & Hardening
*   [DATABASE.md](DATABASE.md) - Schema and ERD
*   [DEVOPS.md](DEVOPS.md) - Cloudflare, Traefik, Containers
*   [FRONTEND_TESTING_STRATEGY.md](FRONTEND_TESTING_STRATEGY.md) - Frontend Test Coverage Strategy
*   [TASKS.md](TASKS.md) / [TEST_USERS.md](TEST_USERS.md)