rede5/gohorsejobs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
gohorsejobs/docs/AGENTS.md

5 KiB
Raw Blame History

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

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 for Candidate and Company personas.

Documentation Index

When asked to learn or modify parts of the system, consult these files first: