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
This commit is contained in:
Claude
parent
cd52071b32
commit
20e2e4d0a2
1 changed files with 265 additions and 0 deletions
265
CLAUDE.md
Normal file
265
CLAUDE.md
Normal file
|
|
@ -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
|
||||
Loading…
Reference in a new issue