docs: Comprehensive root README.md with business flows, monetization, and all documentation links

- Added business value proposition and monetization models
- Added Mermaid diagrams for user flows
- Added links to all 6 docs files
- Added links to component-level documentation
- Updated architecture diagram with all services
- Added project status summary
This commit is contained in:
Tiago Yamamoto 2025-12-26 12:51:36 -03:00
parent cb4fd35dc2
commit db5c0671dc

437
README.md
View file

@ -2,296 +2,317 @@
[![Go](https://img.shields.io/badge/Go-1.24-00ADD8?style=flat-square&logo=go)](https://golang.org/)
[![Next.js](https://img.shields.io/badge/Next.js-15-black?style=flat-square&logo=next.js)](https://nextjs.org/)
[![NestJS](https://img.shields.io/badge/NestJS-11-E0234E?style=flat-square&logo=nestjs)](https://nestjs.com/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-336791?style=flat-square&logo=postgresql)](https://postgresql.org/)
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker)](https://docker.com/)
[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
> 🇧🇷 Plataforma de recrutamento conectando profissionais de tecnologia a oportunidades de emprego.
> 🇧🇷 Plataforma SaaS de recrutamento conectando empresas e profissionais de tecnologia.
---
## 📋 Índice
## 💼 O Negócio
- [Visão Geral](#-visão-geral)
- [Arquitetura](#-arquitetura)
- [Tech Stack](#-tech-stack)
- [Pré-requisitos](#-pré-requisitos)
- [Instalação](#-instalação)
- [Variáveis de Ambiente](#-variáveis-de-ambiente)
- [Scripts Disponíveis](#-scripts-disponíveis)
- [Credenciais de Teste](#-credenciais-de-teste)
- [Documentação da API](#-documentação-da-api)
- [Estrutura de Pastas](#-estrutura-de-pastas)
### Proposta de Valor
**GoHorse Jobs** é uma plataforma completa de recrutamento que conecta empresas a candidatos qualificados, oferecendo:
| Para Empresas | Para Candidatos |
|---------------|-----------------|
| ✅ Publicar vagas ilimitadas | ✅ Buscar vagas com filtros avançados |
| ✅ Gerenciar candidaturas | ✅ Candidatar-se em 1 clique |
| ✅ Chat em tempo real | ✅ Perfil profissional completo |
| ✅ Painel de analytics | ✅ Notificações push |
| ✅ Múltiplos recrutadores | ✅ Favoritar vagas |
### Modelos de Monetização
| Plano | Features | Preço |
|-------|----------|-------|
| **Basic** | 3 vagas/mês, 1 usuário | Grátis |
| **Pro** | 20 vagas/mês, 5 usuários | R$ 199/mês |
| **Enterprise** | Ilimitado, SSO, API | Sob consulta |
---
## 🎯 Visão Geral
## 🔄 Fluxos de Negócio
**GoHorse Jobs** é uma plataforma completa de recrutamento que permite:
### 1. Empresa Publica Vaga
- 🏢 **Empresas**: Publicar vagas, gerenciar candidaturas e comunicar-se com candidatos
- 👤 **Candidatos**: Buscar vagas, candidatar-se e criar perfil profissional
- 👑 **Administradores**: Gerenciar todo o sistema com painel administrativo e dashboards dinâmicos
```mermaid
flowchart LR
A[Empresa] --> B[Registro/Login]
B --> C[Criar Vaga]
C --> D[Pagamento]
D --> E[Vaga Publicada]
E --> F[Candidatos Aplicam]
F --> G[Triagem]
G --> H[Contratação]
```
### 2. Candidato Busca Emprego
```mermaid
flowchart LR
A[Candidato] --> B[Buscar Vagas]
B --> C[Filtrar]
C --> D[Ver Detalhes]
D --> E[Candidatar]
E --> F[Aguardar Resposta]
F --> G[Chat com Recrutador]
G --> H[Contratação]
```
### 3. Registro Rápido + Vaga (Novo!)
```mermaid
flowchart LR
A[/post-job] --> B[Dados da Empresa]
B --> C[Dados da Vaga]
C --> D[Confirmação]
D --> E[Empresa + Vaga Criados]
```
---
## 📚 Documentação
### Documentação Principal
| Documento | Descrição |
|-----------|-----------|
| 📖 [docs/API.md](docs/API.md) | Referência completa da API |
| 🔐 [docs/API_SECURITY.md](docs/API_SECURITY.md) | Autenticação e RBAC |
| 🗄️ [docs/DATABASE.md](docs/DATABASE.md) | Schema do banco de dados |
| 🚀 [docs/DEVOPS.md](docs/DEVOPS.md) | CI/CD, Docker, Kubernetes |
| 🗺️ [docs/ROADMAP.md](docs/ROADMAP.md) | Status e progresso |
| 📋 [docs/TASKS.md](docs/TASKS.md) | Tarefas detalhadas |
### Documentação por Componente
| Componente | Documentação | Tech Stack |
|------------|--------------|------------|
| **Backend** | [backend/BACKEND.md](backend/BACKEND.md) | Go, Clean Architecture, DDD |
| **Frontend** | [frontend/FRONTEND.md](frontend/FRONTEND.md) | Next.js 15, Tailwind, shadcn |
| **Backoffice** | [backoffice/BACKOFFICE.md](backoffice/BACKOFFICE.md) | NestJS, Fastify, Stripe |
| **Seeder** | [seeder-api/README.md](seeder-api/README.md) | Node.js, PostgreSQL |
---
## 🏗️ Arquitetura
O projeto segue uma arquitetura de **microserviços** com três componentes principais:
```mermaid
graph TB
subgraph Frontend
A[Next.js 15<br/>App Router]
subgraph "Frontend (Appwrite)"
FE[Next.js 15]
end
subgraph Backend
B[Go API<br/>Clean Architecture]
subgraph "Backend (Kubernetes)"
API[Go API]
BO[NestJS Backoffice]
end
subgraph Database
C[(PostgreSQL 16)]
subgraph "Database"
DB[(PostgreSQL 16)]
end
subgraph Seeder
D[Node.js<br/>Seeder API]
subgraph "External Services"
MQ[LavinMQ]
S3[Cloudflare R2]
FCM[Firebase FCM]
AW[Appwrite Realtime]
ST[Stripe]
end
A -->|REST API| B
B -->|GORM| C
D -->|pg client| C
FE --> API
FE --> AW
API --> DB
API --> MQ
API --> S3
BO --> DB
BO --> MQ
BO --> FCM
BO --> ST
```
### Padrões Arquiteturais
### Componentes
| Componente | Padrão | Descrição |
|------------|--------|-----------|
| **Backend** | Clean Architecture | Separação em `handlers`, `services`, `models`, `usecases` |
| **Frontend** | App Router | Next.js 15 com Server Components e Client Components |
| **Multi-tenancy** | JWT + Company Context | Isolamento de dados por empresa via middleware |
| Componente | Responsabilidade | Porta |
|------------|------------------|-------|
| **Frontend** | UI, SSR, Auth | 3000 |
| **Backend** | API REST, Business Logic | 8521 |
| **Backoffice** | Stripe, Email, FCM | 3001 |
| **PostgreSQL** | Persistência | 5432 |
| **LavinMQ** | Email Queue | 5672 |
---
## 🛠️ Tech Stack
### Backend
| Tecnologia | Versão | Uso |
|------------|--------|-----|
| Go | 1.24 | Linguagem principal |
| PostgreSQL | 16 | Banco de dados |
| JWT | v5 | Autenticação |
| Swagger | 2.0 | Documentação API |
### Frontend
| Tecnologia | Versão | Uso |
|------------|--------|-----|
| Next.js | 15 | Framework React |
| Tailwind CSS | 4 | Estilização |
| shadcn/ui | - | Componentes UI |
| Zod | 3.x | Validação de schemas |
| React Hook Form | 7.x | Gerenciamento de forms |
### DevOps
### Backend (Go)
| Tecnologia | Uso |
|------------|-----|
| Docker | Containerização |
| Alpine Linux | Imagem base (mínima) |
| Go 1.24 | API REST |
| GORM | ORM |
| JWT v5 | Autenticação |
| Swagger | Documentação |
| BCrypt | Password hashing |
### Frontend (Next.js)
| Tecnologia | Uso |
|------------|-----|
| Next.js 15 | Framework |
| Tailwind 4 | CSS |
| shadcn/ui | Componentes |
| Framer Motion | Animações |
| Appwrite | Realtime |
### Backoffice (NestJS)
| Tecnologia | Uso |
|------------|-----|
| NestJS 11 | Framework |
| Stripe | Pagamentos |
| Nodemailer | Emails |
| Firebase Admin | Push |
---
## 📦 Pré-requisitos
## 🚀 Quick Start
Antes de começar, certifique-se de ter instalado:
### Pré-requisitos
- **Docker** (v24+) e **Docker Compose** (v2+)
- **Go** (v1.24+) - para desenvolvimento local
- **Node.js** (v20+) e **npm** - para frontend e seeder
- **PostgreSQL** (v16+) - se rodar sem Docker
- Docker v24+ ou Go 1.24+
- Node.js v20+
- PostgreSQL v16+
---
## 🚀 Instalação
### Passo a Passo
### Instalação
```bash
# 1. Clone o repositório
# Clone
git clone https://github.com/rede5/gohorsejobs.git
cd gohorsejobs
# 2. Configure as variáveis de ambiente
# Configure
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
cp seeder-api/.env.example seeder-api/.env
# 3. Inicie o banco de dados (PostgreSQL)
# Certifique-se de ter um PostgreSQL rodando na porta 5432
# Ou utilize docker-compose se disponível (verifique k8s/ para manifests)
# Backend
cd backend && go run ./cmd/api
# 4. Inicie o Backend
cd backend
go run ./cmd/api
# Frontend (outro terminal)
cd frontend && npm install && npm run dev
# 5. Em outro terminal, inicie o Frontend
cd frontend
npm install
npm run dev
# 6. (Opcional) Popule o banco com dados de teste
cd seeder-api
npm install
npm run seed
# Seeder (opcional)
cd seeder-api && npm install && npm run seed
```
---
### Usando start.sh
## 🔐 Variáveis de Ambiente
### Backend (`backend/.env`)
| Variável | Descrição | Exemplo |
|----------|-----------|---------|
| `DB_HOST` | Host do PostgreSQL | `localhost` |
| `DB_PORT` | Porta do PostgreSQL | `5432` |
| `DB_USER` | Usuário do banco | `postgres` |
| `DB_PASSWORD` | Senha do banco | `yourpassword` |
| `DB_NAME` | Nome do banco | `gohorsejobs` |
| `JWT_SECRET` | Secret para JWT (min 32 chars) | `your-secret-key-at-least-32-chars` |
| `PORT` | Porta da API | `8080` |
| `ENV` | Ambiente | `development` ou `production` |
| `CORS_ORIGINS` | Origens permitidas | `http://localhost:3000` |
### Frontend (`frontend/.env`)
| Variável | Descrição | Exemplo |
|----------|-----------|---------|
| `NEXT_PUBLIC_API_URL` | URL da API Backend | `http://localhost:8080` |
---
## 📜 Scripts Disponíveis
### Backend (`cd backend`)
| Comando | Descrição |
|---------|-----------|
| `go run ./cmd/api` | Inicia o servidor de desenvolvimento |
| `go build ./cmd/api` | Compila o binário |
| `go test ./...` | Executa todos os testes |
| `swag init -g cmd/api/main.go` | Regenera documentação Swagger |
### Frontend (`cd frontend`)
| Comando | Descrição |
|---------|-----------|
| `npm run dev` | Inicia servidor de desenvolvimento |
| `npm run build` | Compila para produção |
| `npm run start` | Inicia servidor de produção |
| `npm run lint` | Executa linter |
### Seeder API (`cd seeder-api`)
| Comando | Descrição |
|---------|-----------|
| `npm run seed` | Popula banco com todos os dados |
| `npm run seed:reset` | Limpa banco e repopula |
| `npm run seed:users` | Popula apenas usuários |
```bash
./start.sh
# Escolha uma opção:
# 1. Run Backend
# 2. Run Frontend
# 3. Run Seeder
# 4. Run Migrations
# 5. Reset + Seed
```
---
## 🔑 Credenciais de Teste
| Tipo | Usuário | Senha | Dashboard |
|------|---------|-------|-----------|
| **SuperAdmin** | `superadmin` | `Admin@2025!` | `/dashboard/admin` |
| **Admin Empresa** | `takeshi_yamamoto` | `Takeshi@2025` | `/dashboard/empresa` |
| **Recrutador** | `maria_santos` | `User@2025` | `/dashboard/empresa` |
| **Candidato** | `paulo_santos` | `User@2025` | `/dashboard/candidato` |
| Tipo | Login | Senha | Acesso |
|------|-------|-------|--------|
| **SuperAdmin** | `superadmin` | `Admin@2025!` | Full |
| **Company Admin** | `takeshi_yamamoto` | `Takeshi@2025` | Empresa |
| **Recruiter** | `maria_santos` | `User@2025` | Vagas |
| **Candidate** | `paulo_santos` | `User@2025` | Candidato |
---
## 📖 Documentação da API
## 🔧 Environment Variables
### Swagger UI
Acesse a documentação interativa em: **http://localhost:8521/docs/index.html**
### Backend
> **Produção:** https://api-dev.gohorsejobs.com/docs/index.html
```env
DATABASE_URL=postgres://user:pass@host:5432/db
JWT_SECRET=your-secret-key-min-32-chars
PASSWORD_PEPPER=your-pepper
CORS_ORIGINS=https://frontend.com
```
### Modelagem de Banco
Veja a documentação completa do banco de dados em: [docs/DATABASE.md](docs/DATABASE.md)
### Frontend
### Roadmap & Tarefas
- 🗺️ **Roadmap:** [docs/ROADMAP.md](docs/ROADMAP.md) - Status e progresso do projeto
- 📋 **Tarefas:** [docs/TASKS.md](docs/TASKS.md) - Lista detalhada para evitar retrabalho
- 📡 **API:** [docs/API.md](docs/API.md) - Documentação completa com rotas e permissões
```env
NEXT_PUBLIC_API_URL=https://api.gohorsejobs.com
NEXT_PUBLIC_APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
NEXT_PUBLIC_APPWRITE_PROJECT_ID=your-project
```
### Documentação por Componente
| Componente | Documentação |
|------------|--------------|
| **Backend** | [backend/README.md](backend/README.md) |
| **Frontend** | [frontend/README.md](frontend/README.md) |
| **Backoffice** | [backoffice/README.md](backoffice/README.md) |
| **Seeder** | [seeder-api/README.md](seeder-api/README.md) |
### Backoffice
### Endpoints Principais
| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| `GET` | `/` | Info da API + IP | ❌ |
| `GET` | `/health` | Health check | ❌ |
| `POST` | `/api/v1/auth/login` | Login | ❌ |
| `POST` | `/api/v1/companies` | Criar empresa | ❌ |
| `GET` | `/api/v1/companies` | Listar empresas | ❌ |
| `GET` | `/api/v1/users` | Listar usuários | ✅ JWT |
| `POST` | `/api/v1/users` | Criar usuário | ✅ JWT |
| `DELETE` | `/api/v1/users/{id}` | Deletar usuário | ✅ JWT |
| `GET` | `/jobs` | Listar vagas | ❌ |
| `POST` | `/jobs` | Criar vaga | ❌ |
| `GET` | `/jobs/{id}` | Detalhes da vaga | ❌ |
| `PUT` | `/jobs/{id}` | Atualizar vaga | ❌ |
| `DELETE` | `/jobs/{id}` | Deletar vaga | ❌ |
| `GET` | `/api/v1/users/me` | Perfil do usuário | ✅ JWT |
```env
DATABASE_URL=postgres://user:pass@host:5432/db
STRIPE_SECRET_KEY=sk_test_xxx
AMQP_URL=amqp://user:pass@host:5672
```
---
## 📂 Estrutura de Pastas
## 📂 Estrutura
```
gohorsejobs/
├── backend/ # API Go
│ ├── cmd/api/ # Entrypoint da aplicação
│ ├── internal/ # Código interno
│ │ ├── api/ # Handlers e middlewares (Clean Arch)
│ │ ├── core/ # Domain e UseCases (DDD)
│ │ ├── database/ # Conexão com banco
│ │ ├── dto/ # Data Transfer Objects
│ │ ├── handlers/ # Controllers (legacy)
│ │ ├── middleware/ # Middlewares de segurança
│ │ ├── models/ # Entidades do banco
│ │ ├── router/ # Configuração de rotas
│ │ ├── services/ # Lógica de negócios
│ │ └── utils/ # Utilitários (JWT, sanitizer)
│ ├── migrations/ # Migrations SQL
│ └── docs/ # Swagger gerado
├── backend/ # Go API (Clean Architecture)
│ ├── cmd/api/ # Entrypoint
│ ├── internal/ # Business logic
│ ├── migrations/ # 30 SQL migrations
│ └── BACKEND.md # Documentação
├── frontend/ # Next.js App
│ └── src/
│ ├── app/ # App Router (páginas)
│ ├── components/ # Componentes React
│ ├── contexts/ # React Contexts
│ ├── hooks/ # Custom Hooks
│ └── lib/ # Utilitários
├── frontend/ # Next.js 15 App
│ ├── src/app/ # 35 pages
│ ├── src/components/ # 44 components
│ └── FRONTEND.md # Documentação
├── seeder-api/ # Seeder Node.js
│ └── src/
│ ├── seeders/ # Scripts de seed por entidade
│ └── index.js # Entrypoint
├── backoffice/ # NestJS API
│ ├── src/ # 7 modules
│ └── BACKOFFICE.md # Documentação
└── README.md # Este arquivo
├── seeder-api/ # Node.js Seeder
│ └── README.md # Documentação
├── docs/ # Documentação central
│ ├── API.md
│ ├── API_SECURITY.md
│ ├── DATABASE.md
│ ├── DEVOPS.md
│ ├── ROADMAP.md
│ └── TASKS.md
├── k8s/ # Kubernetes manifests
│ ├── dev/
│ ├── hml/
│ └── prd/
└── start.sh # Script de inicialização
```
---
## 📊 Status do Projeto
| Área | Progresso | Status |
|------|-----------|--------|
| Backend API | 95% | 🟢 Production Ready |
| Frontend | 85% | 🟢 Funcional |
| Backoffice | 80% | 🟢 Funcional |
| Seeder | 100% | 🟢 Completo |
| Documentação | 95% | 🟢 Atualizada |
Ver [docs/ROADMAP.md](docs/ROADMAP.md) para detalhes.
---
## 🤝 Contribuindo
1. Fork o projeto
@ -304,7 +325,7 @@ gohorsejobs/
## 📄 Licença
Este projeto está sob a licença MIT. Veja o arquivo [LICENSE](LICENSE) para mais detalhes.
Este projeto está sob a licença MIT. Veja [LICENSE](LICENSE) para detalhes.
---