From 20e2e4d0a260201673535c478440708c42d605c2 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 12 Feb 2026 17:28:11 +0000 Subject: [PATCH] Add comprehensive CLAUDE.md for AI assistant onboarding Documents the monorepo structure, tech stack, build/test commands, architecture conventions, authentication setup, database schema, API routes, and deployment workflows across all four services. https://claude.ai/code/session_01D77GLdc91KshbUAfyuEEwh --- CLAUDE.md | 265 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 265 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b0cc5da --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,265 @@ +# 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 + +```bash +./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) + +```bash +# 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) + +```bash +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) + +```bash +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 + +```bash +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