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

12 KiB
Raw Blame History

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
forgejo git@pipe.gohorsejobs.com:bohessefm/gohorsejobs.git Forgejo via SSH
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