Tiago Yamamoto 7934afcf0d docs: complete project documentation overhaul

- Add comprehensive root README with badges, architecture diagram, and setup guide
- Update backend README with security middlewares and endpoint documentation
- Update frontend README with design system and page structure
- Update seeder-api README with generated data and credentials
- Add internal module READMEs (middleware, handlers, components)
- Document Clean Architecture layers and request flow
- Add environment variables reference table

2025-12-09 19:36:36 -03:00

8.9 KiB

Raw Blame History

🐴 GoHorse Jobs

🇧🇷 Plataforma de recrutamento conectando profissionais de tecnologia a oportunidades de emprego.

📋 Índice

Visão Geral
Arquitetura
Tech Stack
Pré-requisitos
Instalação
Variáveis de Ambiente
Scripts Disponíveis
Credenciais de Teste
Documentação da API
Estrutura de Pastas

🎯 Visão Geral

GoHorse Jobs é uma plataforma completa de recrutamento que permite:

🏢 Empresas: Publicar vagas, gerenciar candidaturas e comunicar-se com candidatos
👤 Candidatos: Buscar vagas, candidatar-se e acompanhar status
👑 Administradores: Gerenciar todo o sistema com painel administrativo

🏗️ Arquitetura

O projeto segue uma arquitetura de microserviços com três componentes principais:

graph TB
    subgraph Frontend
        A[Next.js 15<br/>App Router]
    end
    
    subgraph Backend
        B[Go API<br/>Clean Architecture]
    end
    
    subgraph Database
        C[(PostgreSQL 16)]
    end
    
    subgraph Seeder
        D[Node.js<br/>Seeder API]
    end
    
    A -->|REST API| B
    B -->|GORM| C
    D -->|pg client| C

Padrões Arquiteturais

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

🛠️ 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

Tecnologia	Uso
Docker	Containerização
Alpine Linux	Imagem base (mínima)

📦 Pré-requisitos

Antes de começar, certifique-se de ter instalado:

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

🚀 Instalação

Opção 1: Script de Desenvolvimento (Recomendado)

# Clone o repositório
git clone https://github.com/rede5/gohorsejobs.git
cd gohorsejobs

# Execute o script de desenvolvimento
./run_dev.sh

Opção 2: Manual (Passo a Passo)

# 1. Clone o repositório
git clone https://github.com/rede5/gohorsejobs.git
cd gohorsejobs

# 2. Configure as variáveis de ambiente
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

# 4. Inicie o Backend
cd backend
go run ./cmd/api

# 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

🔐 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

Raiz do Projeto

Comando	Descrição
`./run_dev.sh`	Inicia backend + frontend em modo desenvolvimento
`./run_dev_seed.sh`	Inicia tudo + popula banco com dados de teste

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

🔑 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`	`Maria@2025`	`/dashboard/empresa`
Candidato	`paulo_santos`	`User@2025`	`/dashboard/candidato`

📖 Documentação da API

Swagger UI

Acesse a documentação interativa em: http://localhost:8080/swagger/index.html

Endpoints Principais

Método	Endpoint	Descrição	Autenticação
`GET`	`/health`	Health check	❌
`POST`	`/api/v1/auth/login`	Login	❌
`POST`	`/api/v1/companies`	Criar empresa	❌
`GET`	`/api/v1/users`	Listar usuários	✅ JWT
`POST`	`/api/v1/users`	Criar usuário	✅ JWT
`GET`	`/jobs`	Listar vagas	❌
`POST`	`/jobs`	Criar vaga	✅ JWT

📂 Estrutura de Pastas

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
│
├── frontend/                # Next.js App
│   └── src/
│       ├── app/             # App Router (páginas)
│       ├── components/      # Componentes React
│       ├── contexts/        # React Contexts
│       ├── hooks/           # Custom Hooks
│       └── lib/             # Utilitários
│
├── seeder-api/              # Seeder Node.js
│   └── src/
│       ├── seeders/         # Scripts de seed por entidade
│       └── index.js         # Entrypoint
│
├── run_dev.sh               # Script de desenvolvimento
└── README.md                # Este arquivo

🤝 Contribuindo

Fork o projeto
Crie sua branch (git checkout -b feature/AmazingFeature)
Commit suas mudanças (git commit -m 'feat: add amazing feature')
Push para a branch (git push origin feature/AmazingFeature)
Abra um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

_{Desenvolvido com ❤️ pela equipe GoHorse}

8.9 KiB Raw Blame History