From 6ec54460f870ef92f41716ef7a37c9e2b97da1d3 Mon Sep 17 00:00:00 2001 From: Tiago Yamamoto Date: Mon, 16 Feb 2026 05:57:02 -0600 Subject: [PATCH] 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 --- .agent/workflows/deploy-frontend.md | 48 ------- .agent/workflows/sync-remotes.md | 11 -- AGENTS.md | 5 + README.md | 40 +++--- backend/BACKEND.md | 2 +- docs/{root/CLAUDE.md => AGENTS.md} | 214 ++++++++++++++------------- docs/API.md | 2 +- docs/API_SECURITY.md | 2 +- docs/DATABASE.md | 2 +- docs/DEVOPS.md | 2 +- docs/TASKS.md | 2 +- docs/WORKFLOWS.md | 215 ++++++++++++++++++++++++++++ docs/root/ARCHITECTURE.md | 69 --------- docs/root/ROADMAP.md | 7 - docs/root/STATUS_REPORT.md | 8 -- frontend/FRONTEND.md | 2 +- 16 files changed, 348 insertions(+), 283 deletions(-) delete mode 100644 .agent/workflows/deploy-frontend.md delete mode 100644 .agent/workflows/sync-remotes.md create mode 100644 AGENTS.md rename docs/{root/CLAUDE.md => AGENTS.md} (60%) create mode 100644 docs/WORKFLOWS.md delete mode 100644 docs/root/ARCHITECTURE.md delete mode 100644 docs/root/ROADMAP.md delete mode 100644 docs/root/STATUS_REPORT.md diff --git a/.agent/workflows/deploy-frontend.md b/.agent/workflows/deploy-frontend.md deleted file mode 100644 index 404698b..0000000 --- a/.agent/workflows/deploy-frontend.md +++ /dev/null @@ -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` | diff --git a/.agent/workflows/sync-remotes.md b/.agent/workflows/sync-remotes.md deleted file mode 100644 index 7771f2c..0000000 --- a/.agent/workflows/sync-remotes.md +++ /dev/null @@ -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 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0f111c8 --- /dev/null +++ b/AGENTS.md @@ -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. diff --git a/README.md b/README.md index ca25e61..5475f91 100644 --- a/README.md +++ b/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 --- diff --git a/backend/BACKEND.md b/backend/BACKEND.md index 35d5380..ae93caa 100755 --- a/backend/BACKEND.md +++ b/backend/BACKEND.md @@ -3,7 +3,7 @@ [![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/) -> **Last Updated:** 2024-12-29 +> **Last Updated:** 2026-02-16 API REST desenvolvida em Go seguindo princípios de **Clean Architecture** e **DDD**. diff --git a/docs/root/CLAUDE.md b/docs/AGENTS.md similarity index 60% rename from docs/root/CLAUDE.md rename to docs/AGENTS.md index 3f7c4a4..b6f6874 100644 --- a/docs/root/CLAUDE.md +++ b/docs/AGENTS.md @@ -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 | diff --git a/docs/API.md b/docs/API.md index 5808add..312cdc5 100644 --- a/docs/API.md +++ b/docs/API.md @@ -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 diff --git a/docs/API_SECURITY.md b/docs/API_SECURITY.md index 539d234..4b60004 100644 --- a/docs/API_SECURITY.md +++ b/docs/API_SECURITY.md @@ -2,7 +2,7 @@ Security layers, authentication methods, and RBAC for GoHorse Jobs API. -> **Last Updated:** 2024-12-26 +> **Last Updated:** 2026-02-16 --- diff --git a/docs/DATABASE.md b/docs/DATABASE.md index d822263..5c9dd4a 100644 --- a/docs/DATABASE.md +++ b/docs/DATABASE.md @@ -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 diff --git a/docs/DEVOPS.md b/docs/DEVOPS.md index db62edd..73ab789 100644 --- a/docs/DEVOPS.md +++ b/docs/DEVOPS.md @@ -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) diff --git a/docs/TASKS.md b/docs/TASKS.md index 29771d2..6b97bc9 100644 --- a/docs/TASKS.md +++ b/docs/TASKS.md @@ -2,7 +2,7 @@ Lista detalhada de tarefas para evitar retrabalho. -> **Last Updated:** 2024-12-26 +> **Last Updated:** 2026-02-16 --- diff --git a/docs/WORKFLOWS.md b/docs/WORKFLOWS.md new file mode 100644 index 0000000..25954c0 --- /dev/null +++ b/docs/WORKFLOWS.md @@ -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 ` for details +2. Verify user has podman permissions (rootless or sudo) diff --git a/docs/root/ARCHITECTURE.md b/docs/root/ARCHITECTURE.md deleted file mode 100644 index 5a7618f..0000000 --- a/docs/root/ARCHITECTURE.md +++ /dev/null @@ -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`. - diff --git a/docs/root/ROADMAP.md b/docs/root/ROADMAP.md deleted file mode 100644 index d76ac16..0000000 --- a/docs/root/ROADMAP.md +++ /dev/null @@ -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) diff --git a/docs/root/STATUS_REPORT.md b/docs/root/STATUS_REPORT.md deleted file mode 100644 index 5338a45..0000000 --- a/docs/root/STATUS_REPORT.md +++ /dev/null @@ -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) diff --git a/frontend/FRONTEND.md b/frontend/FRONTEND.md index 383d75b..4af7b1f 100644 --- a/frontend/FRONTEND.md +++ b/frontend/FRONTEND.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 ---