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
106 lines
5.2 KiB
Markdown
106 lines
5.2 KiB
Markdown
# 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)
|
|
|