gohorsejobs/docs/root/CLAUDE.md

CLAUDE.md - GoHorse Jobs

Project Overview

GoHorse Jobs is a B2B SaaS recruitment platform connecting companies with candidates. It is structured as a monorepo with multiple services sharing a single PostgreSQL database.

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

Repository Structure

gohorsejobs/
├── backend/              # Go 1.24 REST API (Clean Architecture + DDD)
├── frontend/             # Next.js 15 web application (App Router)
├── backoffice/           # NestJS 11 admin/worker API (Fastify adapter)
├── seeder-api/           # Node.js Express database seeder
├── job-scraper-multisite/# Job scraping service
├── ass-email/            # Email assistant service
├── k8s/                  # Kubernetes manifests (dev, hml, prd)
├── docs/                 # Central documentation (API, DB, DevOps, Roadmap)
├── .forgejo/             # Forgejo CI/CD workflows
├── .drone.yml            # Drone CI/CD pipelines (dev/hml/prd)
└── start.sh              # Interactive dev startup script

Tech Stack

Service	Language	Framework	Key Libraries
Backend	Go 1.24	stdlib net/http	JWT v5, lib/pq, GORM, Stripe, AWS SDK v2, RabbitMQ, Firebase Admin, Swaggo
Frontend	TypeScript 5	Next.js 15 (App Router)	React 19, Tailwind CSS 4, shadcn/ui (Radix), Zustand, React Hook Form + Zod, Framer Motion, Appwrite, Firebase
Backoffice	TypeScript 5	NestJS 11 (Fastify)	TypeORM, Passport + JWT, Stripe, AMQP, Nodemailer, Pino, Firebase Admin
Seeder	JavaScript (ESM)	Express 5	pg, bcrypt

Database: PostgreSQL 16+ with UUID v7 primary keys. 42 SQL migration files in backend/migrations/.

Quick Start

./start.sh   # Interactive menu

Option	Action
1	Start Frontend + Backend
2	Reset DB + Seed + Start
3	Start all services (Frontend + Backend + Backoffice)
4	Run migrations only
5	Seed database (append)
6	Full DB reset + migrate + seed
7	Run backend E2E tests
8	Seed reset LITE (skip 153k cities)
9	Run all tests (Backend + Frontend)

Service Ports

Service	Port
Backend	8521
Frontend	8963
Backoffice	3001
Swagger (Backend)	8521/swagger/index.html
Swagger (Backoffice)	3001/api/docs

Build & Test Commands

Backend (Go)

# Run
cd backend && go run cmd/api/main.go

# Test
go test -v ./... -count=1                         # All unit tests
go test -tags=e2e -v ./tests/e2e/...              # E2E tests

# Swagger generation (requires swag CLI)
swag init -g cmd/api/main.go --parseDependency --parseInternal

# Dependencies
go mod tidy

Frontend (Next.js)

cd frontend
npm install          # Install deps
npm run dev          # Dev server (default port 3000, use -p 8963 for project convention)
npm run build        # Production build
npm run lint         # ESLint (next lint)
npm run test         # Jest unit tests

Backoffice (NestJS)

cd backoffice
pnpm install          # Uses pnpm (packageManager: pnpm@9.15.4)
npm run start:dev     # Dev server with watch
npm run build         # Production build (nest build)
npm run lint          # ESLint with auto-fix
npm run format        # Prettier
npm run test          # Jest unit tests
npm run test:cov      # Coverage
npm run test:e2e      # E2E tests

Seeder

cd seeder-api
npm install
npm run migrate       # Run migrations
npm run seed          # Seed data
npm run seed:reset    # Drop all tables
npm run seed:lite     # Seed without 153k cities

Architecture & Conventions

Backend (Go) - Clean Architecture + DDD

backend/internal/
├── api/              # (legacy) HTTP handlers
├── handlers/         # HTTP request handlers (current)
├── middleware/        # Auth, CORS, rate limiting, security headers, XSS sanitizer
├── core/
│   ├── domain/entity/ # Business entities (User, Company, Job, etc.)
│   ├── ports/         # Repository interfaces
│   └── usecases/      # Business logic (LoginUseCase, RegisterUseCase, etc.)
├── infrastructure/
│   ├── auth/          # JWT service
│   ├── persistence/   # PostgreSQL repository implementations
│   └── storage/       # S3/R2 storage adapter
├── services/          # Business services (Email, FCM, Storage, Admin)
├── dto/               # Data Transfer Objects
├── router/            # Route definitions
├── models/            # GORM models (legacy, being migrated)
├── database/          # DB connection & migration runner
└── utils/             # Utilities (JWT, sanitizer)

Patterns:

• Constructor injection: func NewService(db *sql.DB) *Service
• All DB operations accept ctx context.Context
• Error handling: (T, error) return tuples
• Repository interfaces in core/ports/, implementations in infrastructure/persistence/
• Test files: *_test.go

Frontend (Next.js) - App Router

frontend/src/
├── app/               # File-based routing (20+ routes)
│   ├── dashboard/     # Protected routes (12+ sub-pages)
│   ├── jobs/          # Job listing & details
│   ├── auth/          # Login, register flows
│   └── ...
├── components/        # Reusable components (44+)
│   └── ui/            # shadcn/ui primitives (24+)
├── hooks/             # Custom React hooks (useAuth, useFetch, etc.)
├── contexts/          # React contexts (auth, theme)
├── lib/               # Utilities (API calls, validation helpers)
└── i18n/              # Internationalization (PT, EN, ES, JA)

Patterns:

• Server Components by default; use 'use client' directive for interactivity
• Tailwind CSS utility classes for styling
• Path alias: @/* maps to ./src/*
• Form validation: React Hook Form + Zod schemas
• Global state: Zustand stores
• Real-time features: Appwrite SDK
• Test files: *.test.tsx

Backoffice (NestJS) - Modular

backoffice/src/
├── admin/             # Dashboard & statistics
├── auth/              # JWT authentication (Passport)
├── email/             # Email worker (AMQP/LavinMQ consumer)
├── external-services/ # Credential management
├── fcm-tokens/        # Firebase push tokens
├── plans/             # Subscription plans
├── stripe/            # Stripe payment integration
├── tickets/           # Support tickets
├── activity-logs/     # Activity tracking
└── credentials/       # External credentials management

Patterns:

• NestJS module pattern: *.module.ts, *.controller.ts, *.service.ts, *.entity.ts
• Guards for auth: @UseGuards(JwtAuthGuard)
• DTOs: create-*.dto.ts, update-*.dto.ts with class-validator decorators
• Prettier config: single quotes, trailing commas

Authentication & Authorization

• JWT: HS256 with HttpOnly cookies (web) + Bearer tokens (API/mobile)
• 4 roles: superadmin > admin > recruiter > candidate
• Middleware stack: Auth (JWT+RBAC) -> CORS -> Rate Limiting (100 req/min) -> Security Headers -> XSS Sanitizer
• JWT secret must match between Backend and Backoffice services

Database

• PostgreSQL 16+ with UUID v7 for primary keys (SERIAL for reference tables)
• Migrations: backend/migrations/ (42 SQL files, numbered 000_ through 999_)
• Core tables: users, companies, user_companies, jobs, applications, favorite_jobs, notifications, tickets, activity_logs, job_payments
• Relationships: Users belong to companies via user_companies; jobs belong to companies; applications link users to jobs

API Routes

All backend routes under /api/v1:

• Auth: /auth/login, /auth/register/candidate, /auth/register/company, /auth/forgot-password, /auth/reset-password
• Jobs: CRUD at /jobs, moderation at /jobs/moderation
• Companies: CRUD at /companies, status management
• Users: /users/me (profile), admin CRUD at /users
• Applications: /applications with status updates
• Storage: /storage/upload-url (presigned S3/R2 URLs)
• Admin: /admin/companies, /admin/email-templates, /admin/email-settings
• Notifications: /notifications, /tokens (FCM)
• Chat: /conversations, /conversations/{id}/messages

External Services

Service	Purpose
Stripe	Payment processing & subscriptions
Firebase (FCM)	Push notifications
Appwrite	Real-time chat/messaging
LavinMQ (AMQP)	Message queue for background jobs
Cloudflare R2 / S3	File/image storage
Resend	Transactional email
cPanel API	Email account management

Deployment

• Environments: dev (branch: dev), hml (branch: hml), prd (branch: main)
• CI/CD: Forgejo workflows (.forgejo/workflows/deploy.yaml) + Drone (.drone.yml)
• Container runtime: Podman (dev), Kubernetes (production)
• Registry: Forgejo (forgejo-gru.rede5.com.br/rede5/) and Harbor (in.gohorsejobs.com)
• Docker images: gohorsejobs-backend, gohorsejobs-frontend, gohorsejobs-backoffice, gohorsejobs-seeder

Documentation

Detailed docs are in the docs/ directory:

• docs/API.md - Complete API reference
• docs/API_SECURITY.md - Authentication & RBAC details
• docs/DATABASE.md - Schema & ERD
• docs/DEVOPS.md - Infrastructure & deployment
• docs/ROADMAP.md - Product roadmap
• docs/TASKS.md - Task tracking

Key Things to Know

• The backend uses Clean Architecture with DDD; always respect the layer boundaries (handlers -> usecases -> ports/repositories)
• Frontend uses Next.js App Router conventions; new pages go in src/app/, shared components in src/components/
• The backoffice is a separate NestJS service that shares the same PostgreSQL database as the backend
• Migrations are plain SQL files executed by the seeder-api; they are not managed by an ORM migration tool
• The project supports 4 languages (PT, EN, ES, JA) via i18n message files in frontend/src/i18n/
• Environment variables must be configured in .env files for each service (backend, frontend, backoffice, seeder-api); these files are gitignored
• The start.sh script is the recommended way to run the development environment

Git Workflow

Remotes

Remote	URL	Funcao
origin	git@github.com:rede5/gohorsejobs.git	GitHub - desenvolvimento principal
pipe	https://pipe.gohorsejobs.com/bohessefm/gohorsejobs.git	Forgejo - mirror/CI
dokku	dokku@localhost:gohorsejobs	Deploy Dokku (gohorsejobs)
dokku-frontend	dokku@localhost:gohorse-frontend	Deploy Dokku (frontend)

Fluxo de Desenvolvimento

O desenvolvimento acontece no GitHub (origin). O Forgejo (pipe) eh um mirror que recebe o codigo via push manual.

GitHub (origin)  --->  VPS vim  --->  Forgejo (pipe)
   [dev]          git pull        git push pipe dev

Passo a passo para sincronizar:

# 1. Na VPS, puxar as alteracoes do GitHub
cd /root/gohorsejobs
git pull origin dev

# 2. Enviar para o Forgejo
git push pipe dev

# 3. (Opcional) Enviar para outras branches
git pull origin main && git push pipe main
git pull origin hml && git push pipe hml

Branches

Branch	Ambiente	Descricao
dev	Desenvolvimento	Branch principal de trabalho
hml	Homologacao	Testes pre-producao
main	Producao	Versao estavel

Regras

1. Todo desenvolvimento acontece no GitHub (origin) - PRs, code review, CI
2. Forgejo (pipe) eh mirror - recebe push manual apos pull do GitHub
3. Nunca commitar direto no Forgejo - sempre via GitHub primeiro
4. Deploy via Dokku - push para remotes dokku/dokku-frontend para deploy na VPS