gohorsejobs/docs/root/ARCHITECTURE.md

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.