Documentação — Sistema Administrativo do Clube de Programação

Documentação técnica do sistema. Comece por Instalação se você só quer rodar o projeto.

Estrutura do repositório

.
├── assets/originais/     Arquivos de câmera e arte como vieram. FONTE, não é
│                         servido: `backend/scripts/otimizar-imagens.py` gera
│                         os derivados de `src/public/images/` a partir daqui.
├── backend/              A aplicação inteira (NestJS + Nunjucks + Prisma).
│   ├── api/index.js      Ponto de entrada da função na Vercel.
│   ├── prisma/           Schema do banco.
│   ├── scripts/          Utilitários de manutenção (imagens, admin, build).
│   ├── src/              Código, templates (`views/`) e estáticos (`public/`).
│   └── test/             Testes e2e.
├── docs/                 Documentação técnica — o índice abaixo.
│   └── interno/          Material da diretoria. Git-ignorado de propósito.
└── vercel.json           Build e roteamento do deploy.

Duas regras que explicam por que as pastas estão assim:

• Original nunca fica em src/public/. O que está lá é servido; foto de 6 MB de câmera não pode estar ao alcance de um <img>.
• Documento interno nunca é commitado. O repositório é público, e docs/interno/ existe justamente para o material que não pode ir junto.

Índice

Documento	Para quê
Instalação	Subir o projeto localmente do zero
Configuração	Todas as variáveis de ambiente e o que acontece sem cada uma
Arquitetura	Como o código está organizado e por quê
Rotas	Mapa completo das rotas HTTP
Autenticação e permissões	Sessão, CSRF e o que cada cargo pode fazer
Banco de dados	Modelos, enums e como aplicar o schema
Templates e front-end	Nunjucks, filtros herdados do Django, CSS e JS
Imagens e fontes	Assets do site público
Deploy	Publicação na Vercel
Correções aplicadas	O que estava quebrado e o que foi feito
Solução de problemas	Erros comuns e como resolver

Visão geral em 30 segundos

Aplicação web administrativa de um clube de programação: membros, setores, tarefas em kanban, anexos e um fluxo de solicitação de cadastro com aprovação.

• Renderização no servidor. Não é uma SPA. O NestJS renderiza HTML com Nunjucks e os formulários fazem POST tradicional com redirect.
• Stack: NestJS (Express) + Prisma + PostgreSQL (Supabase), sessão em cookie via iron-session e Cloudinary para anexos.
• Origem: é a reescrita de um sistema Django. Vários nomes de rota, campos de formulário e filtros de template foram mantidos por compatibilidade — isso está sinalizado ao longo dos documentos.