rede5/gohorsejobs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs: unify documentation structure

Browse source 
- 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 2026-02-16 05:57:02 -06:00
parent 6fbd1f5ffc
commit 6ec54460f8
16 changed files with 348 additions and 283 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
.agent/workflows/deploy-frontend.md
View file

@ -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` |

11
.agent/workflows/sync-remotes.md
View file

@ -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
View 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
View file

@ -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/); ### Por componente
- 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).
--- - [backend/BACKEND.md](backend/BACKEND.md) — API Go
- [frontend/FRONTEND.md](frontend/FRONTEND.md) — Next.js
## 📚 Onde encontrar cada assunto - [backoffice/BACKOFFICE.md](backoffice/BACKOFFICE.md) — NestJS
- [seeder-api/SEEDER-API.md](seeder-api/SEEDER-API.md) — Seeder
### 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)
--- ---

2
backend/BACKEND.md
View file

@ -3,7 +3,7 @@
[![Go](https://img.shields.io/badge/Go-1.24-00ADD8?style=flat-square&logo=go)](https://golang.org/) [![Go](https://img.shields.io/badge/Go-1.24-00ADD8?style=flat-square&logo=go)](https://golang.org/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-336791?style=flat-square&logo=postgresql)](https://postgresql.org/) [![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-336791?style=flat-square&logo=postgresql)](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**. API REST desenvolvida em Go seguindo princípios de **Clean Architecture** e **DDD**.

200
docs/root/CLAUDE.md → docs/AGENTS.md
View file

@ -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 ## 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). **Business model**: Freemium (Free / Pro R$199/month / Enterprise custom pricing).
---
## Repository Structure ## Repository Structure
``` ```
@ -15,24 +22,27 @@ gohorsejobs/
├── backoffice/ # NestJS 11 admin/worker API (Fastify adapter) ├── backoffice/ # NestJS 11 admin/worker API (Fastify adapter)
├── seeder-api/ # Node.js Express database seeder ├── seeder-api/ # Node.js Express database seeder
├── job-scraper-multisite/# Job scraping service ├── job-scraper-multisite/# Job scraping service
├── ass-email/ # Email assistant service
├── k8s/ # Kubernetes manifests (dev, hml, prd) ├── k8s/ # Kubernetes manifests (dev, hml, prd)
├── docs/ # Central documentation (API, DB, DevOps, Roadmap) ├── docs/ # Central documentation
├── .forgejo/ # Forgejo CI/CD workflows ├── .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 └── start.sh # Interactive dev startup script
``` ```
---
## Tech Stack ## Tech Stack
| Service | Language | Framework | Key Libraries | | 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 | | 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 | | Backoffice | TypeScript 5 | NestJS 11 (Fastify) | TypeORM, Passport + JWT, Stripe, AMQP, Nodemailer, Pino, Firebase Admin |
| Seeder | JavaScript (ESM) | Express 5 | pg, bcrypt | | 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 ## Quick Start
@ -62,23 +72,18 @@ gohorsejobs/
| Swagger (Backend) | 8521/swagger/index.html | | Swagger (Backend) | 8521/swagger/index.html |
| Swagger (Backoffice) | 3001/api/docs | | Swagger (Backoffice) | 3001/api/docs |
---
## Build & Test Commands ## Build & Test Commands
### Backend (Go) ### Backend (Go)
```bash ```bash
# Run cd backend && go run cmd/api/main.go # Run
cd backend && go run cmd/api/main.go
# Test
go test -v ./... -count=1 # All unit tests go test -v ./... -count=1 # All unit tests
go test -tags=e2e -v ./tests/e2e/... # E2E tests go test -tags=e2e -v ./tests/e2e/... # E2E tests
swag init -g cmd/api/main.go --parseDependency --parseInternal # Swagger
# Swagger generation (requires swag CLI) go mod tidy # Dependencies
swag init -g cmd/api/main.go --parseDependency --parseInternal
# Dependencies
go mod tidy
``` ```
### Frontend (Next.js) ### Frontend (Next.js)
@ -86,9 +91,9 @@ go mod tidy
```bash ```bash
cd frontend cd frontend
npm install # Install deps 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 build # Production build
npm run lint # ESLint (next lint) npm run lint # ESLint
npm run test # Jest unit tests npm run test # Jest unit tests
``` ```
@ -96,13 +101,11 @@ npm run test # Jest unit tests
```bash ```bash
cd backoffice 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 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 lint # ESLint with auto-fix
npm run format # Prettier
npm run test # Jest unit tests npm run test # Jest unit tests
npm run test:cov # Coverage
npm run test:e2e # E2E tests 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 npm run seed:lite # Seed without 153k cities
``` ```
---
## Architecture & Conventions ## Architecture & Conventions
### Backend (Go) - Clean Architecture + DDD ### Backend (Go) - Clean Architecture + DDD
@ -125,7 +130,7 @@ npm run seed:lite # Seed without 153k cities
backend/internal/ backend/internal/
├── api/ # (legacy) HTTP handlers ├── api/ # (legacy) HTTP handlers
├── handlers/ # HTTP request handlers (current) ├── handlers/ # HTTP request handlers (current)
├── middleware/ # Auth, CORS, rate limiting, security headers, XSS sanitizer ├── middleware/ # Auth, CORS, rate limiting, security headers
├── core/ ├── core/
│ ├── domain/entity/ # Business entities (User, Company, Job, etc.) │ ├── domain/entity/ # Business entities (User, Company, Job, etc.)
│ ├── ports/ # Repository interfaces │ ├── ports/ # Repository interfaces
@ -156,23 +161,21 @@ frontend/src/
├── app/ # File-based routing (20+ routes) ├── app/ # File-based routing (20+ routes)
│ ├── dashboard/ # Protected routes (12+ sub-pages) │ ├── dashboard/ # Protected routes (12+ sub-pages)
│ ├── jobs/ # Job listing & details │ ├── jobs/ # Job listing & details
│ ├── auth/ # Login, register flows │ └── auth/ # Login, register flows
│ └── ...
├── components/ # Reusable components (44+) ├── components/ # Reusable components (44+)
│ └── ui/ # shadcn/ui primitives (24+) │ └── ui/ # shadcn/ui primitives (24+)
├── hooks/ # Custom React hooks (useAuth, useFetch, etc.) ├── hooks/ # Custom React hooks
├── contexts/ # React contexts (auth, theme) ├── contexts/ # React contexts (auth, theme)
├── lib/ # Utilities (API calls, validation helpers) ├── lib/ # Utilities (API calls, validation)
└── i18n/ # Internationalization (PT, EN, ES, JA) └── i18n/ # Internationalization (PT, EN, ES, JA)
``` ```
**Patterns**: **Patterns**:
- Server Components by default; use `'use client'` directive for interactivity - Server Components by default; use `'use client'` for interactivity
- Tailwind CSS utility classes for styling - Tailwind CSS utility classes
- Path alias: `@/*` maps to `./src/*` - Path alias: `@/*` maps to `./src/*`
- Form validation: React Hook Form + Zod schemas - Form validation: React Hook Form + Zod schemas
- Global state: Zustand stores - Global state: Zustand stores
- Real-time features: Appwrite SDK
- Test files: `*.test.tsx` - Test files: `*.test.tsx`
### Backoffice (NestJS) - Modular ### Backoffice (NestJS) - Modular
@ -186,30 +189,33 @@ backoffice/src/
├── fcm-tokens/ # Firebase push tokens ├── fcm-tokens/ # Firebase push tokens
├── plans/ # Subscription plans ├── plans/ # Subscription plans
├── stripe/ # Stripe payment integration ├── stripe/ # Stripe payment integration
├── tickets/ # Support tickets └── tickets/ # Support tickets
├── activity-logs/ # Activity tracking
└── credentials/ # External credentials management
``` ```
**Patterns**: **Patterns**:
- NestJS module pattern: `*.module.ts`, `*.controller.ts`, `*.service.ts`, `*.entity.ts` - NestJS module pattern: `*.module.ts`, `*.controller.ts`, `*.service.ts`
- Guards for auth: `@UseGuards(JwtAuthGuard)` - Guards: `@UseGuards(JwtAuthGuard)`
- DTOs: `create-*.dto.ts`, `update-*.dto.ts` with class-validator decorators - DTOs: `create-*.dto.ts`, `update-*.dto.ts` with class-validator
- Prettier config: single quotes, trailing commas - Prettier: single quotes, trailing commas
---
## Authentication & Authorization ## Authentication & Authorization
- **JWT**: HS256 with HttpOnly cookies (web) + Bearer tokens (API/mobile) - **JWT**: HS256 with HttpOnly cookies (web) + Bearer tokens (API/mobile)
- **4 roles**: `superadmin` > `admin` > `recruiter` > `candidate` - **4 roles**: `superadmin` > `admin` > `recruiter` > `candidate`
- **Middleware stack**: Auth (JWT+RBAC) -> CORS -> Rate Limiting (100 req/min) -> Security Headers -> XSS Sanitizer - **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 ## Database
- PostgreSQL 16+ with UUID v7 for primary keys (SERIAL for reference tables) - 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` - 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 ## API Routes
@ -224,6 +230,8 @@ All backend routes under `/api/v1`:
- **Notifications**: `/notifications`, `/tokens` (FCM) - **Notifications**: `/notifications`, `/tokens` (FCM)
- **Chat**: `/conversations`, `/conversations/{id}/messages` - **Chat**: `/conversations`, `/conversations/{id}/messages`
---
## External Services ## External Services
| Service | Purpose | | Service | Purpose |
@ -234,82 +242,70 @@ All backend routes under `/api/v1`:
| LavinMQ (AMQP) | Message queue for background jobs | | LavinMQ (AMQP) | Message queue for background jobs |
| Cloudflare R2 / S3 | File/image storage | | Cloudflare R2 / S3 | File/image storage |
| Resend | Transactional email | | Resend | Transactional email |
| cPanel API | Email account management |
---
## Deployment ## Deployment
- **Environments**: `dev` (branch: dev), `hml` (branch: hml), `prd` (branch: main) - **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) - **Container runtime**: Podman (dev), Kubernetes (production)
- **Registry**: Forgejo (`forgejo-gru.rede5.com.br/rede5/`) and Harbor (`in.gohorsejobs.com`) - **Registry**: Forgejo (`forgejo-gru.rede5.com.br/rede5/`)
- **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 ## Git Workflow
### Remotes ### Remotes
| Remote | URL | Funcao | | Remote | URL | Function |
|--------|-----|--------| |--------|-----|----------|
| **origin** | git@github.com:rede5/gohorsejobs.git | GitHub - desenvolvimento principal | | **origin** | git@github.com:rede5/gohorsejobs.git | GitHub - main development |
| **pipe** | https://pipe.gohorsejobs.com/bohessefm/gohorsejobs.git | Forgejo - mirror/CI | | **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 ### Branches
| Branch | Ambiente | Descricao | | Branch | Environment | Description |
|--------|----------|-----------| |--------|-------------|-------------|
| **dev** | Desenvolvimento | Branch principal de trabalho | | **dev** | Development | Main working branch |
| **hml** | Homologacao | Testes pre-producao | | **hml** | Staging | Pre-production testing |
| **main** | Producao | Versao estavel | | **main** | Production | Stable release |
### Regras ### Sync Flow
1. **Todo desenvolvimento acontece no GitHub** (origin) - PRs, code review, CI ```bash
2. **Forgejo (pipe) eh mirror** - recebe push manual apos pull do GitHub # 1. Pull from GitHub
3. **Nunca commitar direto no Forgejo** - sempre via GitHub primeiro git pull origin dev
4. **Deploy via Dokku** - push para remotes dokku/dokku-frontend para deploy na VPS
# 2. Push to Forgejo (pipe)
git push pipe dev
```
---
## Key Things to Know
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
docs/API.md
View file

@ -2,7 +2,7 @@
Complete API reference with routes, permissions, and modules. 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` > **Base URL:** `https://api.gohorsejobs.com/api/v1`
> **Auth:** JWT Bearer Token or HttpOnly Cookie > **Auth:** JWT Bearer Token or HttpOnly Cookie

2
docs/API_SECURITY.md
View file

@ -2,7 +2,7 @@
Security layers, authentication methods, and RBAC for GoHorse Jobs API. Security layers, authentication methods, and RBAC for GoHorse Jobs API.
> **Last Updated:** 2024-12-26 > **Last Updated:** 2026-02-16
--- ---

2
docs/DATABASE.md
View file

@ -2,7 +2,7 @@
Complete database documentation for the GoHorseJobs platform. Complete database documentation for the GoHorseJobs platform.
> **Last Updated:** 2026-01-03 > **Last Updated:** 2026-02-16
> **Database:** PostgreSQL 16+ (Local `postgres-main` container) > **Database:** PostgreSQL 16+ (Local `postgres-main` container)
> **Connection:** Internal `gohorsejobs_dev` database via `web_proxy` network > **Connection:** Internal `gohorsejobs_dev` database via `web_proxy` network
> **ID Strategy:** UUID v7 for core tables, SERIAL for reference tables > **ID Strategy:** UUID v7 for core tables, SERIAL for reference tables

2
docs/DEVOPS.md
View file

@ -2,7 +2,7 @@
Infraestrutura, CI/CD e deploy do projeto GoHorseJobs no servidor `apolo`. Infraestrutura, CI/CD e deploy do projeto GoHorseJobs no servidor `apolo`.
> **Last Updated:** 2026-01-03 > **Last Updated:** 2026-02-16
> **Server:** Apolo VPS > **Server:** Apolo VPS
> **Tech Stack:** Podman, Systemd (Quadlet), Traefik, PostgreSQL (Local) > **Tech Stack:** Podman, Systemd (Quadlet), Traefik, PostgreSQL (Local)

2
docs/TASKS.md
View file

@ -2,7 +2,7 @@
Lista detalhada de tarefas para evitar retrabalho. Lista detalhada de tarefas para evitar retrabalho.
> **Last Updated:** 2024-12-26 > **Last Updated:** 2026-02-16
--- ---

215
docs/WORKFLOWS.md Normal file
View 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)

69
docs/root/ARCHITECTURE.md
View file

@ -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`.

7
docs/root/ROADMAP.md
View file

@ -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)

8
docs/root/STATUS_REPORT.md
View file

@ -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)

2
frontend/FRONTEND.md
View file

@ -6,7 +6,7 @@
Frontend da plataforma GoHorse Jobs construído com **Next.js 15** e **App Router**. Frontend da plataforma GoHorse Jobs construído com **Next.js 15** e **App Router**.
> **Last Updated:** 2026-01-03 > **Last Updated:** 2026-02-16
--- ---