docs: unify documentation structure
- Create docs/AGENTS.md for AI assistants context - Create docs/WORKFLOWS.md consolidating deployment workflows - Remove redundant docs/root/ folder - Remove .agent/ folder (consolidated into docs/) - Update dates in all documentation files - Simplify README.md documentation section
This commit is contained in:
Tiago Yamamoto
parent
6fbd1f5ffc
commit
6ec54460f8
16 changed files with 348 additions and 283 deletions
|
|
@ -1,48 +0,0 @@
|
|||
---
|
||||
description: Deploy Frontend to Apolo (dev.gohorsejobs.com)
|
||||
---
|
||||
# Deploy Frontend
|
||||
|
||||
**IMPORTANT**: Always use `--build-arg` to set production URLs. Never rely on Dockerfile defaults.
|
||||
|
||||
// turbo-all
|
||||
|
||||
## Steps
|
||||
|
||||
1. Login to Forgejo Registry:
|
||||
```bash
|
||||
podman login -u 'y@rede5.com.br' forgejo-gru.rede5.com.br
|
||||
```
|
||||
|
||||
2. Build with Production URLs:
|
||||
```bash
|
||||
cd /home/yamamoto/lab/gohorsejobs
|
||||
podman build \
|
||||
--build-arg NEXT_PUBLIC_API_URL=https://api-tmp.gohorsejobs.com \
|
||||
--build-arg NEXT_PUBLIC_BACKOFFICE_URL=https://b-tmp.gohorsejobs.com \
|
||||
-t forgejo-gru.rede5.com.br/rede5/gohorsejobs-frontend:latest \
|
||||
-f frontend/Dockerfile frontend/
|
||||
```
|
||||
|
||||
3. Push to Registry:
|
||||
```bash
|
||||
podman push forgejo-gru.rede5.com.br/rede5/gohorsejobs-frontend:latest
|
||||
```
|
||||
|
||||
4. Deploy on Apolo:
|
||||
```bash
|
||||
ssh root@apolo 'podman pull forgejo-gru.rede5.com.br/rede5/gohorsejobs-frontend:latest && systemctl restart gohorsejobs-frontend-dev'
|
||||
```
|
||||
|
||||
5. Verify:
|
||||
```bash
|
||||
ssh root@apolo 'systemctl status gohorsejobs-frontend-dev --no-pager | tail -5'
|
||||
```
|
||||
|
||||
## Environment Reference
|
||||
|
||||
| Variable | Production Value |
|
||||
|----------|------------------|
|
||||
| `NEXT_PUBLIC_API_URL` | `https://api-tmp.gohorsejobs.com` |
|
||||
| `NEXT_PUBLIC_BACKOFFICE_URL` | `https://b-tmp.gohorsejobs.com` |
|
||||
| `NEXT_PUBLIC_SEEDER_API_URL` | `https://seeder.gohorsejobs.com` |
|
||||
|
|
@ -1,11 +0,0 @@
|
|||
---
|
||||
description: Push changes to both Forgejo (origin) and GitHub remotes
|
||||
---
|
||||
|
||||
1. Push to Forgejo (Origin)
|
||||
// turbo
|
||||
git push origin HEAD
|
||||
|
||||
2. Push to GitHub
|
||||
// turbo
|
||||
git push github HEAD
|
||||
5
AGENTS.md
Normal file
5
AGENTS.md
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
# AGENTS.md
|
||||
|
||||
> **Redirect:** This file has moved to [docs/AGENTS.md](docs/AGENTS.md)
|
||||
|
||||
Context for AI coding assistants (Claude, Cursor, etc.) is now maintained in the central documentation folder.
|
||||
40
README.md
40
README.md
|
|
@ -9,33 +9,25 @@ Plataforma de recrutamento com arquitetura separada por serviços:
|
|||
|
||||
---
|
||||
|
||||
## ✅ Estado atual da documentação
|
||||
## 📚 Documentação
|
||||
|
||||
Este repositório tinha documentação duplicada e com partes desatualizadas. A partir desta revisão:
|
||||
| Documento | Descrição |
|
||||
|-----------|-----------|
|
||||
| [docs/AGENTS.md](docs/AGENTS.md) | Contexto para assistentes de IA (Claude, Cursor, etc.) |
|
||||
| [docs/API.md](docs/API.md) | Endpoints, contratos e exemplos |
|
||||
| [docs/API_SECURITY.md](docs/API_SECURITY.md) | Autenticação, autorização e segurança |
|
||||
| [docs/DATABASE.md](docs/DATABASE.md) | Estrutura e decisões de dados |
|
||||
| [docs/DEVOPS.md](docs/DEVOPS.md) | Execução local, deploy e operação |
|
||||
| [docs/WORKFLOWS.md](docs/WORKFLOWS.md) | Fluxos de deploy e operações |
|
||||
| [docs/ROADMAP.md](docs/ROADMAP.md) | Direção de produto e engenharia |
|
||||
| [docs/TASKS.md](docs/TASKS.md) | Tarefas e acompanhamento |
|
||||
|
||||
- a **fonte canônica** de documentação geral passa a ser a pasta [`docs/`](docs/);
|
||||
- arquivos antigos na raiz (ex.: `ROADMAP.md`, `STATUS_REPORT.md`) foram reduzidos para ponteiros;
|
||||
- o roadmap foi simplificado para refletir prioridades reais do produto (sem backlog histórico de iniciativas fora de escopo atual).
|
||||
### Por componente
|
||||
|
||||
---
|
||||
|
||||
## 📚 Onde encontrar cada assunto
|
||||
|
||||
### Documentação central (canônica)
|
||||
|
||||
- [docs/API.md](docs/API.md) — endpoints, contratos e exemplos.
|
||||
- [docs/API_SECURITY.md](docs/API_SECURITY.md) — autenticação, autorização e segurança.
|
||||
- [docs/DATABASE.md](docs/DATABASE.md) — estrutura e decisões de dados.
|
||||
- [docs/DEVOPS.md](docs/DEVOPS.md) — execução local, deploy e operação.
|
||||
- [docs/ROADMAP.md](docs/ROADMAP.md) — direção de produto e engenharia.
|
||||
- [docs/TASKS.md](docs/TASKS.md) — tarefas e acompanhamento de execução.
|
||||
|
||||
### Documentação por componente
|
||||
|
||||
- [backend/BACKEND.md](backend/BACKEND.md)
|
||||
- [frontend/FRONTEND.md](frontend/FRONTEND.md)
|
||||
- [backoffice/BACKOFFICE.md](backoffice/BACKOFFICE.md)
|
||||
- [seeder-api/SEEDER-API.md](seeder-api/SEEDER-API.md)
|
||||
- [backend/BACKEND.md](backend/BACKEND.md) — API Go
|
||||
- [frontend/FRONTEND.md](frontend/FRONTEND.md) — Next.js
|
||||
- [backoffice/BACKOFFICE.md](backoffice/BACKOFFICE.md) — NestJS
|
||||
- [seeder-api/SEEDER-API.md](seeder-api/SEEDER-API.md) — Seeder
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
[](https://golang.org/)
|
||||
[](https://postgresql.org/)
|
||||
|
||||
> **Last Updated:** 2024-12-29
|
||||
> **Last Updated:** 2026-02-16
|
||||
|
||||
API REST desenvolvida em Go seguindo princípios de **Clean Architecture** e **DDD**.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,9 @@
|
|||
# CLAUDE.md - GoHorse Jobs
|
||||
# AGENTS.md - GoHorse Jobs
|
||||
|
||||
> **Last Updated:** 2026-02-16
|
||||
> **Purpose:** Context for AI coding assistants (Claude, Cursor, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Project Overview
|
||||
|
||||
|
|
@ -6,6 +11,8 @@ GoHorse Jobs is a B2B SaaS recruitment platform connecting companies with candid
|
|||
|
||||
**Business model**: Freemium (Free / Pro R$199/month / Enterprise custom pricing).
|
||||
|
||||
---
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
|
|
@ -15,24 +22,27 @@ gohorsejobs/
|
|||
├── 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)
|
||||
├── docs/ # Central documentation
|
||||
├── .forgejo/ # Forgejo CI/CD workflows
|
||||
├── .drone.yml # Drone CI/CD pipelines (dev/hml/prd)
|
||||
├── .drone.yml # Drone CI/CD pipelines
|
||||
└── 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 |
|
||||
| Frontend | TypeScript 5 | Next.js 15 (App Router) | React 19, Tailwind CSS 4, shadcn/ui, Zustand, React Hook Form + Zod, Framer Motion |
|
||||
| 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/`.
|
||||
**Database**: PostgreSQL 16+ with UUID v7 primary keys. 43+ SQL migration files in `backend/migrations/`.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
|
|
@ -62,23 +72,18 @@ gohorsejobs/
|
|||
| 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
|
||||
cd backend && go run cmd/api/main.go # Run
|
||||
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
|
||||
swag init -g cmd/api/main.go --parseDependency --parseInternal # Swagger
|
||||
go mod tidy # Dependencies
|
||||
```
|
||||
|
||||
### Frontend (Next.js)
|
||||
|
|
@ -86,9 +91,9 @@ go mod tidy
|
|||
```bash
|
||||
cd frontend
|
||||
npm install # Install deps
|
||||
npm run dev # Dev server (default port 3000, use -p 8963 for project convention)
|
||||
npm run dev # Dev server (use -p 8963 for project convention)
|
||||
npm run build # Production build
|
||||
npm run lint # ESLint (next lint)
|
||||
npm run lint # ESLint
|
||||
npm run test # Jest unit tests
|
||||
```
|
||||
|
||||
|
|
@ -96,13 +101,11 @@ npm run test # Jest unit tests
|
|||
|
||||
```bash
|
||||
cd backoffice
|
||||
pnpm install # Uses pnpm (packageManager: pnpm@9.15.4)
|
||||
pnpm install # Uses pnpm
|
||||
npm run start:dev # Dev server with watch
|
||||
npm run build # Production build (nest build)
|
||||
npm run build # Production 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
|
||||
```
|
||||
|
||||
|
|
@ -117,6 +120,8 @@ npm run seed:reset # Drop all tables
|
|||
npm run seed:lite # Seed without 153k cities
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture & Conventions
|
||||
|
||||
### Backend (Go) - Clean Architecture + DDD
|
||||
|
|
@ -125,7 +130,7 @@ npm run seed:lite # Seed without 153k cities
|
|||
backend/internal/
|
||||
├── api/ # (legacy) HTTP handlers
|
||||
├── handlers/ # HTTP request handlers (current)
|
||||
├── middleware/ # Auth, CORS, rate limiting, security headers, XSS sanitizer
|
||||
├── middleware/ # Auth, CORS, rate limiting, security headers
|
||||
├── core/
|
||||
│ ├── domain/entity/ # Business entities (User, Company, Job, etc.)
|
||||
│ ├── ports/ # Repository interfaces
|
||||
|
|
@ -156,23 +161,21 @@ frontend/src/
|
|||
├── app/ # File-based routing (20+ routes)
|
||||
│ ├── dashboard/ # Protected routes (12+ sub-pages)
|
||||
│ ├── jobs/ # Job listing & details
|
||||
│ ├── auth/ # Login, register flows
|
||||
│ └── ...
|
||||
│ └── auth/ # Login, register flows
|
||||
├── components/ # Reusable components (44+)
|
||||
│ └── ui/ # shadcn/ui primitives (24+)
|
||||
├── hooks/ # Custom React hooks (useAuth, useFetch, etc.)
|
||||
├── hooks/ # Custom React hooks
|
||||
├── contexts/ # React contexts (auth, theme)
|
||||
├── lib/ # Utilities (API calls, validation helpers)
|
||||
├── lib/ # Utilities (API calls, validation)
|
||||
└── i18n/ # Internationalization (PT, EN, ES, JA)
|
||||
```
|
||||
|
||||
**Patterns**:
|
||||
- Server Components by default; use `'use client'` directive for interactivity
|
||||
- Tailwind CSS utility classes for styling
|
||||
- Server Components by default; use `'use client'` for interactivity
|
||||
- Tailwind CSS utility classes
|
||||
- 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
|
||||
|
|
@ -186,30 +189,33 @@ backoffice/src/
|
|||
├── fcm-tokens/ # Firebase push tokens
|
||||
├── plans/ # Subscription plans
|
||||
├── stripe/ # Stripe payment integration
|
||||
├── tickets/ # Support tickets
|
||||
├── activity-logs/ # Activity tracking
|
||||
└── credentials/ # External credentials management
|
||||
└── tickets/ # Support tickets
|
||||
```
|
||||
|
||||
**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
|
||||
- NestJS module pattern: `*.module.ts`, `*.controller.ts`, `*.service.ts`
|
||||
- Guards: `@UseGuards(JwtAuthGuard)`
|
||||
- DTOs: `create-*.dto.ts`, `update-*.dto.ts` with class-validator
|
||||
- Prettier: 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
|
||||
- **JWT secret must match** between Backend and Backoffice
|
||||
|
||||
---
|
||||
|
||||
## Database
|
||||
|
||||
- PostgreSQL 16+ with UUID v7 for primary keys (SERIAL for reference tables)
|
||||
- Migrations: `backend/migrations/` (42 SQL files, numbered `000_` through `999_`)
|
||||
- Migrations: `backend/migrations/` (43+ 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
|
||||
|
||||
|
|
@ -224,6 +230,8 @@ All backend routes under `/api/v1`:
|
|||
- **Notifications**: `/notifications`, `/tokens` (FCM)
|
||||
- **Chat**: `/conversations`, `/conversations/{id}/messages`
|
||||
|
||||
---
|
||||
|
||||
## External Services
|
||||
|
||||
| Service | Purpose |
|
||||
|
|
@ -234,82 +242,70 @@ All backend routes under `/api/v1`:
|
|||
| 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`)
|
||||
- **CI/CD**: Forgejo workflows (`.forgejo/workflows/`) + 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`
|
||||
- **Registry**: Forgejo (`forgejo-gru.rede5.com.br/rede5/`)
|
||||
|
||||
## 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
|
||||
## Git Workflow
|
||||
|
||||
### Remotes
|
||||
|
||||
| Remote | URL | Function |
|
||||
|--------|-----|----------|
|
||||
| **origin** | git@github.com:rede5/gohorsejobs.git | GitHub - main development |
|
||||
| **pipe** | https://pipe.gohorsejobs.com/bohessefm/gohorsejobs.git | Forgejo - mirror/CI |
|
||||
|
||||
### Branches
|
||||
|
||||
| Branch | Environment | Description |
|
||||
|--------|-------------|-------------|
|
||||
| **dev** | Development | Main working branch |
|
||||
| **hml** | Staging | Pre-production testing |
|
||||
| **main** | Production | Stable release |
|
||||
|
||||
### Sync Flow
|
||||
|
||||
```bash
|
||||
# 1. Pull from GitHub
|
||||
git pull origin dev
|
||||
|
||||
# 2. Push to Forgejo (pipe)
|
||||
git push pipe dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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:**
|
||||
|
||||
```bash
|
||||
# 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
|
||||
1. Backend uses Clean Architecture + DDD; respect layer boundaries (handlers -> usecases -> ports/repositories)
|
||||
2. Frontend uses Next.js App Router; pages in `src/app/`, components in `src/components/`
|
||||
3. Backoffice shares the same PostgreSQL database as the backend
|
||||
4. Migrations are plain SQL files, not managed by an ORM
|
||||
5. Project supports 4 languages (PT, EN, ES, JA) via i18n
|
||||
6. Environment variables in `.env` files (gitignored)
|
||||
7. Use `start.sh` for local development
|
||||
|
||||
---
|
||||
|
||||
## Documentation Index
|
||||
|
||||
| Document | Location | Description |
|
||||
|----------|----------|-------------|
|
||||
| API Reference | [API.md](API.md) | Endpoints, contracts, examples |
|
||||
| API Security | [API_SECURITY.md](API_SECURITY.md) | Auth, RBAC, permissions |
|
||||
| Database Schema | [DATABASE.md](DATABASE.md) | Tables, ERD, migrations |
|
||||
| DevOps | [DEVOPS.md](DEVOPS.md) | Infrastructure, deployment |
|
||||
| Roadmap | [ROADMAP.md](ROADMAP.md) | Product direction |
|
||||
| Tasks | [TASKS.md](TASKS.md) | Task tracking |
|
||||
| Workflows | [WORKFLOWS.md](WORKFLOWS.md) | Deployment workflows |
|
||||
| Backend | [../backend/BACKEND.md](../backend/BACKEND.md) | Go API details |
|
||||
| Frontend | [../frontend/FRONTEND.md](../frontend/FRONTEND.md) | Next.js details |
|
||||
| Backoffice | [../backoffice/BACKOFFICE.md](../backoffice/BACKOFFICE.md) | NestJS details |
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
Complete API reference with routes, permissions, and modules.
|
||||
|
||||
> **Last Updated:** 2024-12-26
|
||||
> **Last Updated:** 2026-02-16
|
||||
> **Base URL:** `https://api.gohorsejobs.com/api/v1`
|
||||
> **Auth:** JWT Bearer Token or HttpOnly Cookie
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
Security layers, authentication methods, and RBAC for GoHorse Jobs API.
|
||||
|
||||
> **Last Updated:** 2024-12-26
|
||||
> **Last Updated:** 2026-02-16
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
Complete database documentation for the GoHorseJobs platform.
|
||||
|
||||
> **Last Updated:** 2026-01-03
|
||||
> **Last Updated:** 2026-02-16
|
||||
> **Database:** PostgreSQL 16+ (Local `postgres-main` container)
|
||||
> **Connection:** Internal `gohorsejobs_dev` database via `web_proxy` network
|
||||
> **ID Strategy:** UUID v7 for core tables, SERIAL for reference tables
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
Infraestrutura, CI/CD e deploy do projeto GoHorseJobs no servidor `apolo`.
|
||||
|
||||
> **Last Updated:** 2026-01-03
|
||||
> **Last Updated:** 2026-02-16
|
||||
> **Server:** Apolo VPS
|
||||
> **Tech Stack:** Podman, Systemd (Quadlet), Traefik, PostgreSQL (Local)
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
Lista detalhada de tarefas para evitar retrabalho.
|
||||
|
||||
> **Last Updated:** 2024-12-26
|
||||
> **Last Updated:** 2026-02-16
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
215
docs/WORKFLOWS.md
Normal file
215
docs/WORKFLOWS.md
Normal file
|
|
@ -0,0 +1,215 @@
|
|||
# Workflows - GoHorse Jobs
|
||||
|
||||
> **Last Updated:** 2026-02-16
|
||||
> **Purpose:** Deployment and operational workflows
|
||||
|
||||
---
|
||||
|
||||
## Git Sync (GitHub -> Forgejo)
|
||||
|
||||
Push changes to both GitHub (origin) and Forgejo (pipe) remotes.
|
||||
|
||||
### Flow
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Local] -->|git push| B[GitHub origin]
|
||||
B -->|git pull| C[VPS]
|
||||
C -->|git push pipe| D[Forgejo pipe]
|
||||
```
|
||||
|
||||
### Commands
|
||||
|
||||
```bash
|
||||
# 1. Push to GitHub (origin)
|
||||
git push origin HEAD
|
||||
|
||||
# 2. Push to Forgejo (pipe)
|
||||
git push pipe HEAD
|
||||
```
|
||||
|
||||
### Full Sync (from VPS)
|
||||
|
||||
```bash
|
||||
# 1. Pull from GitHub
|
||||
cd /root/gohorsejobs
|
||||
git pull origin dev
|
||||
|
||||
# 2. Push to Forgejo
|
||||
git push pipe dev
|
||||
|
||||
# 3. Sync other branches (optional)
|
||||
git pull origin main && git push pipe main
|
||||
git pull origin hml && git push pipe hml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deploy Frontend
|
||||
|
||||
Deploy Frontend to Apolo server (dev.gohorsejobs.com).
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Podman installed locally
|
||||
- Access to Forgejo registry
|
||||
- SSH access to Apolo server
|
||||
|
||||
### Steps
|
||||
|
||||
```bash
|
||||
# 1. Login to Forgejo Registry
|
||||
podman login -u 'y@rede5.com.br' forgejo-gru.rede5.com.br
|
||||
|
||||
# 2. Build with Production URLs
|
||||
cd /home/yamamoto/lab/gohorsejobs
|
||||
podman build \
|
||||
--build-arg NEXT_PUBLIC_API_URL=https://api-tmp.gohorsejobs.com \
|
||||
--build-arg NEXT_PUBLIC_BACKOFFICE_URL=https://b-tmp.gohorsejobs.com \
|
||||
-t forgejo-gru.rede5.com.br/rede5/gohorsejobs-frontend:latest \
|
||||
-f frontend/Dockerfile frontend/
|
||||
|
||||
# 3. Push to Registry
|
||||
podman push forgejo-gru.rede5.com.br/rede5/gohorsejobs-frontend:latest
|
||||
|
||||
# 4. Deploy on Apolo
|
||||
ssh root@apolo 'podman pull forgejo-gru.rede5.com.br/rede5/gohorsejobs-frontend:latest && systemctl restart gohorsejobs-frontend-dev'
|
||||
|
||||
# 5. Verify
|
||||
ssh root@apolo 'systemctl status gohorsejobs-frontend-dev --no-pager | tail -5'
|
||||
```
|
||||
|
||||
### Environment Reference
|
||||
|
||||
| Variable | Production Value |
|
||||
|----------|------------------|
|
||||
| `NEXT_PUBLIC_API_URL` | `https://api-tmp.gohorsejobs.com` |
|
||||
| `NEXT_PUBLIC_BACKOFFICE_URL` | `https://b-tmp.gohorsejobs.com` |
|
||||
| `NEXT_PUBLIC_SEEDER_API_URL` | `https://seeder.gohorsejobs.com` |
|
||||
|
||||
---
|
||||
|
||||
## Deploy Backend
|
||||
|
||||
Deploy Backend API to Apolo server (api-tmp.gohorsejobs.com).
|
||||
|
||||
### Steps
|
||||
|
||||
```bash
|
||||
# 1. Login to Forgejo Registry
|
||||
podman login forgejo-gru.rede5.com.br
|
||||
|
||||
# 2. Build
|
||||
cd backend
|
||||
podman build -t forgejo-gru.rede5.com.br/rede5/gohorsejobs-backend:latest .
|
||||
|
||||
# 3. Push
|
||||
podman push forgejo-gru.rede5.com.br/rede5/gohorsejobs-backend:latest
|
||||
|
||||
# 4. Deploy on Apolo
|
||||
ssh root@apolo 'podman pull forgejo-gru.rede5.com.br/rede5/gohorsejobs-backend:latest && systemctl restart gohorsejobs-backend-dev'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deploy Backoffice
|
||||
|
||||
Deploy Backoffice API to Apolo server (b-tmp.gohorsejobs.com).
|
||||
|
||||
### Steps
|
||||
|
||||
```bash
|
||||
# 1. Build
|
||||
cd backoffice
|
||||
podman build -t forgejo-gru.rede5.com.br/rede5/gohorsejobs-backoffice:latest .
|
||||
|
||||
# 2. Push
|
||||
podman push forgejo-gru.rede5.com.br/rede5/gohorsejobs-backoffice:latest
|
||||
|
||||
# 3. Deploy
|
||||
ssh root@apolo 'podman pull forgejo-gru.rede5.com.br/rede5/gohorsejobs-backoffice:latest && systemctl restart gohorsejobs-backoffice-dev'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Database Operations
|
||||
|
||||
### Run Migrations
|
||||
|
||||
```bash
|
||||
# Local
|
||||
cd backend && go run ./cmd/manual_migrate
|
||||
|
||||
# Via SSH (remote)
|
||||
ssh root@apolo 'cd /mnt/data/gohorsejobs/backend && ./migrate.sh'
|
||||
```
|
||||
|
||||
### Seed Database
|
||||
|
||||
```bash
|
||||
# Trigger Seeder API
|
||||
curl -X POST https://seeder.gohorsejobs.com/seed
|
||||
|
||||
# Local
|
||||
cd seeder-api && npm run seed
|
||||
```
|
||||
|
||||
### Database Shell
|
||||
|
||||
```bash
|
||||
# Via SSH
|
||||
ssh root@apolo 'podman exec -it postgres-main psql -U yuki -d gohorsejobs_dev'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Service Management (Apolo)
|
||||
|
||||
### View Status
|
||||
|
||||
```bash
|
||||
ssh root@apolo 'systemctl status gohorsejobs-backend-dev --no-pager'
|
||||
ssh root@apolo 'systemctl status gohorsejobs-frontend-dev --no-pager'
|
||||
ssh root@apolo 'systemctl status gohorsejobs-backoffice-dev --no-pager'
|
||||
ssh root@apolo 'systemctl status gohorsejobs-seeder-dev --no-pager'
|
||||
```
|
||||
|
||||
### Restart Services
|
||||
|
||||
```bash
|
||||
# All services
|
||||
ssh root@apolo 'systemctl restart gohorsejobs-backend-dev gohorsejobs-frontend-dev gohorsejobs-backoffice-dev gohorsejobs-seeder-dev'
|
||||
|
||||
# Individual service
|
||||
ssh root@apolo 'systemctl restart gohorsejobs-backend-dev'
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
ssh root@apolo 'journalctl -u gohorsejobs-backend-dev -f --no-pager'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### CI/CD Workflow Not Starting
|
||||
|
||||
**Symptom**: "Waiting for runner..."
|
||||
|
||||
**Solution**:
|
||||
1. Check `.forgejo/workflows/deploy.yaml` for `runs-on` label
|
||||
2. Verify runner has matching label in config
|
||||
|
||||
### SSH Connection Failed
|
||||
|
||||
**Solution**:
|
||||
1. Verify public key is in `~/.ssh/authorized_keys`
|
||||
2. Check IP accessibility from runner network
|
||||
|
||||
### Build Failed in Podman
|
||||
|
||||
**Solution**:
|
||||
1. Run `podman logs -f <container>` for details
|
||||
2. Verify user has podman permissions (rootless or sudo)
|
||||
|
|
@ -1,69 +0,0 @@
|
|||
# GoHorse Jobs – Visão de Arquitetura
|
||||
|
||||
## Backend (Clean Architecture)
|
||||
|
||||
### Fluxo de dados
|
||||
1. **Router (HTTP)** recebe as requisições e direciona para handlers. (`backend/internal/router/router.go`).
|
||||
2. **Handlers** fazem validações básicas e delegam para **Use Cases** (core) ou serviços legados. (`backend/internal/api/handlers`, `backend/internal/handlers`).
|
||||
3. **Use Cases** (core) orquestram regras de negócio e dependem de **repositórios/infrastructure**. (`backend/internal/core/usecases`, `backend/internal/infrastructure`).
|
||||
4. **Repos/Services** persistem dados e retornam **Models** que são serializados em JSON. (`backend/internal/models`).
|
||||
|
||||
### Domínio (entidades reais)
|
||||
As entidades do domínio vivem em `backend/internal/core/domain/entity` e definem a semântica do negócio. Exemplos principais:
|
||||
- **User** com roles, status e perfil completo. (`backend/internal/core/domain/entity/user.go`).
|
||||
- **Company (Tenant)** com status e dados de contato. (`backend/internal/core/domain/entity/company.go`).
|
||||
- **Location** (Country/State/City). (`backend/internal/core/domain/entity/location.go`).
|
||||
- **Roles/Permissions** para RBAC. (`backend/internal/core/domain/entity/permission.go`).
|
||||
|
||||
### Contratos HTTP (Models)
|
||||
Os contratos expostos via JSON são definidos em `backend/internal/models`.
|
||||
Principais modelos:
|
||||
- **Job** com salário, workMode, employmentType, requisitos/benefícios e status. (`backend/internal/models/job.go`).
|
||||
- **Company** com branding, endereço, status e metadados. (`backend/internal/models/company.go`).
|
||||
- **User** e **UserResponse** (público). (`backend/internal/models/user.go`).
|
||||
- **Application** e **ApplicationWithDetails** (job + applicant). (`backend/internal/models/application.go`).
|
||||
- **Location** (Region/City). (`backend/internal/models/location.go`).
|
||||
- **Notification**, **Ticket**, **LoginAudit**, **FavoriteJob**, **Tag**. (`backend/internal/models/notification.go`, `backend/internal/models/ticket.go`, `backend/internal/models/login_audit.go`, `backend/internal/models/favorite_job.go`, `backend/internal/models/tag.go`).
|
||||
|
||||
### Rotas principais (v1)
|
||||
O roteamento está centralizado em `backend/internal/router/router.go` com exemplos:
|
||||
- **Auth**: `/api/v1/auth/login`, `/api/v1/auth/register`, `/api/v1/auth/logout`.
|
||||
- **Users**: `/api/v1/users`, `/api/v1/users/{id}`, `/api/v1/users/me`.
|
||||
- **Companies**: `/api/v1/companies` e ações de admin para status.
|
||||
- **Jobs**: `/api/v1/jobs` e `/api/v1/jobs/{id}`.
|
||||
|
||||
## Frontend (Next.js App Router)
|
||||
|
||||
### Estrutura
|
||||
- **App Router**: páginas e layouts em `frontend/src/app`.
|
||||
- **Componentes**: `frontend/src/components` e UI padronizada em `frontend/src/components/ui`.
|
||||
- **Contexts**: `frontend/src/contexts` (AuthContext, ConfigContext, ThemeContext, notification-context).
|
||||
- **Lib**: `frontend/src/lib` para `api.ts`, `types.ts`, `i18n.tsx` e helpers.
|
||||
|
||||
### Tipos e contratos
|
||||
- O frontend consome os contratos definidos em `frontend/src/lib/types.ts`.
|
||||
- **Regra de ouro**: comparar `frontend/src/lib/types.ts` com `backend/internal/models` sempre que um campo mudar.
|
||||
|
||||
### i18n
|
||||
- Strings de UI usadas pelo `useTranslation` ficam em `frontend/src/i18n/*.json` e são carregadas por `frontend/src/lib/i18n.tsx`.
|
||||
- Há um catálogo adicional em `frontend/messages/*.json` com traduções gerais do produto (ex.: `pt-BR.json`).
|
||||
|
||||
## Variáveis de ambiente críticas (.env.example)
|
||||
|
||||
### Backend
|
||||
- **Banco**: `DATABASE_URL`.
|
||||
- **Auth**: `JWT_SECRET`, `JWT_EXPIRATION`, `PASSWORD_PEPPER`, `COOKIE_SECRET`, `COOKIE_DOMAIN`.
|
||||
- **Servidor**: `BACKEND_PORT`, `BACKEND_HOST`, `ENV`, `CORS_ORIGINS`.
|
||||
- **Storage/S3**: `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT`, `S3_BUCKET`.
|
||||
- **Cloudflare**: `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ZONE_ID`.
|
||||
- **Stripe**: `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PUBLISHABLE_KEY`.
|
||||
- **Email**: `RESEND_API_KEY`, `EMAIL_FROM`, `APP_URL`.
|
||||
- **Mensageria**: `AMQP_URL`.
|
||||
|
||||
### Frontend
|
||||
- **API**: `NEXT_PUBLIC_API_URL`.
|
||||
- **Backoffice**: `NEXT_PUBLIC_BACKOFFICE_URL`.
|
||||
- **Seeder API**: `NEXT_PUBLIC_SEEDER_API_URL`.
|
||||
- **Scraper API**: `NEXT_PUBLIC_SCRAPER_API_URL`.
|
||||
- **Analytics**: `NEXT_PUBLIC_VERCEL_ANALYTICS`.
|
||||
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
# Roadmap (movido)
|
||||
|
||||
Este arquivo foi mantido apenas por compatibilidade de links antigos.
|
||||
|
||||
A versão oficial e atualizada do roadmap está em:
|
||||
|
||||
- [`docs/ROADMAP.md`](docs/ROADMAP.md)
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
# Status Report (movido)
|
||||
|
||||
Este arquivo foi reduzido para evitar divergência de informação.
|
||||
|
||||
Para status e planejamento atuais, consulte:
|
||||
|
||||
- [`docs/ROADMAP.md`](docs/ROADMAP.md)
|
||||
- [`docs/TASKS.md`](docs/TASKS.md)
|
||||
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
Frontend da plataforma GoHorse Jobs construído com **Next.js 15** e **App Router**.
|
||||
|
||||
> **Last Updated:** 2026-01-03
|
||||
> **Last Updated:** 2026-02-16
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue