Frame-24

Sistema de Gestão Integrada para Cinema

Monorepo full-stack com TypeScript para operação de redes de cinema, com arquitetura multi-tenant, API REST versionada, dashboard web e landing page.

Leitura rápida

Projeto acadêmico em equipe, desenvolvido para Banco de Dados na UNEB Campus 2. O repositório reúne uma API NestJS, aplicações Next.js e uma camada de dados PostgreSQL/Prisma em um monorepo TypeScript.

Para conhecer a implementação:

• Comece em apps/api/src/modules para os recursos de negócio e em packages/db para a modelagem de dados.
• Consulte apps/web e apps/admin para os fluxos de interface.
• Veja apps/api/src/workers para o processamento assíncrono de auditoria.
• Use o Quick Start abaixo para preparar o ambiente e o histórico de commits para identificar as contribuições de cada integrante.

O escopo reúne módulos em diferentes estágios. Integrações externas e recursos planejados devem ser avaliados conforme as limitações documentadas; a presença de um módulo não comprova operação em produção.

---

Sumário

• Visão Geral
• Arquitetura do Monorepo
• Stack Tecnológica
• Pré-requisitos
• Quick Start
• Scripts do Projeto
• Serviços e Portas
• Banco de Dados e Schemas
• Autenticação
• Multi-Tenancy
• Troubleshooting
• Documentação Complementar
• Contribuição
• Licença

Visão Geral

O Frame-24 é um sistema para gestão integrada de operações de cinema, incluindo catálogo, sessões, vendas, fiscal, CRM e processos administrativos.

Principais capacidades

• Gestão de complexos, salas e assentos.
• Programação de sessões com validação de conflitos.
• Venda de ingressos e produtos de concessão.
• Módulos fiscal e financeiro com apurações e repasses.
• CRM com fidelidade e histórico de relacionamento.
• Base multi-tenant com isolamento de dados por empresa.

Arquitetura do Monorepo

O repositório utiliza Turborepo + pnpm workspaces, organizado em apps e packages reutilizáveis.

Apps

App	Descrição	Porta	Stack
api	Backend REST API versionada (/v1) com Swagger/Scalar	4000	NestJS
web	Aplicação web principal para operações	3000	Next.js + React
admin	Dashboard administrativo com componentes compartilhados	3004	Next.js + React
landing-page	Site institucional e fluxo de aquisição	3003	Next.js + React

Packages

Package	Responsabilidade
@repo/db	Prisma schema, migrations e client compartilhado
@repo/ui	Biblioteca de componentes UI reutilizáveis
@repo/eslint-config	Configurações de lint padronizadas
@repo/tailwind-config	Configurações compartilhadas de estilo
@repo/typescript-config	Bases TypeScript reutilizáveis

Stack Tecnológica

Core

• Node.js >= 18
• TypeScript 6.0.2
• pnpm 10.33.0
• Turborepo 2.x

Backend

• NestJS 11
• Prisma ORM
• JWT para autenticação/autorização
• RabbitMQ para mensageria assíncrona

Frontend

• Next.js 16
• React 19
• Tailwind CSS 4

Infraestrutura local (Docker)

• PostgreSQL
• RabbitMQ
• MinIO
• MailHog

Pré-requisitos

Ferramenta	Versão mínima
Node.js	>= 18
pnpm	10.33.0
Docker / Docker Compose	latest
Git	latest

Instalar pnpm

Via npm:

npm install -g pnpm@10.33.0

Via Homebrew (macOS/Linux):

brew install pnpm

Via Chocolatey (Windows):

choco install pnpm

Verificação:

pnpm --version

Quick Start

1. Clone o repositório

git clone https://github.com/Lawtrel/frame-24.git
cd frame-24

2. Suba a infraestrutura com Docker

docker compose up -d

Esse comando sobe PostgreSQL, Redis, RabbitMQ, MinIO e Mailpit. A API e os apps web rodam localmente com pnpm dev.

Para conferir:

docker compose ps

Para parar:

docker compose down

3. Configure variáveis de ambiente para execução local

cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
cp apps/admin/.env.example apps/admin/.env
cp apps/landing-page/.env.example apps/landing-page/.env

Opcional para sobrescrever localmente sem versionar:

touch apps/web/.env.local
touch apps/admin/.env.local

4. Instale dependências

pnpm install

5. Prepare o banco

cd packages/db
pnpm db:generate
pnpm db:migrate:dev
pnpm build
cd ../..

6. Inicie o ambiente local

Todos os serviços de desenvolvimento:

pnpm dev

Apenas API:

pnpm dev:api

Apenas aplicação web:

pnpm dev:web

Apenas dashboard admin:

pnpm dev:admin

Scripts do Projeto

Comandos na raiz:

pnpm dev
pnpm build
pnpm lint
pnpm check-types
pnpm format

Execução por app com Turbo:

turbo dev --filter=api
turbo dev --filter=web
turbo dev --filter=admin
turbo dev --filter=landing-page

Comandos úteis de banco (em packages/db):

pnpm db:generate
pnpm db:migrate:dev --name nome-da-migration
pnpm db:studio
pnpm db:reset

Serviços e Portas

Serviço	URL	Credenciais
API (Swagger)	http://localhost:4000/api/docs	-
Web App	http://localhost:3000	-
Admin App	http://localhost:3004	-
Landing Page	http://localhost:3003	-
RabbitMQ Management	http://localhost:15672	frame24 / frame24pass
MailHog	http://localhost:8025	-

Se alguma porta estiver em uso, sobrescreva ao subir:

POSTGRES_HOST_PORT=15432 \
REDIS_HOST_PORT=16379 \
RABBITMQ_HOST_PORT=15673 \
RABBITMQ_UI_HOST_PORT=15674 \
MINIO_HOST_PORT=19000 \
MINIO_CONSOLE_HOST_PORT=19001 \
MAILPIT_SMTP_HOST_PORT=11025 \
MAILPIT_UI_HOST_PORT=18025 \
docker compose up -d

Prisma Studio:

cd packages/db
pnpm db:studio

Banco de Dados e Schemas

O sistema usa modelagem multi-schema com isolamento por domínio.

Schemas principais:

• identity (usuários, empresas, autenticação, permissões)
• hr (recursos humanos)
• finance (contabilidade e lançamentos)
• crm (clientes e fidelidade)
• sales (ingressos, concessão e transações)
• inventory (fornecedores, produtos, estoque)
• marketing (campanhas, cupons, descontos)
• operations (complexos, salas, sessões, assentos)
• projects (projetos RECINE)
• stock (movimentação de estoque)
• tax (tributos e apurações fiscais)
• catalog (filmes, produtos, combos)
• contracts (contratos com distribuidoras)

Autenticação

Contrato de autenticação (padrão do projeto):

• Cadastro admin legado: POST /v1/auth/register
• Cadastro cliente legado: POST /v1/customer/auth/register
• Login/cadastro oficial: Better Auth em /api/auth/* (email/senha, sessão e recuperação de sessão).
• Endpoints legados de login (/v1/auth/login e /v1/customer/auth/login) foram removidos.

Headers aceitos na API:

Authorization: Bearer <access-token>

Variáveis principais da API:

JWT_SECRET=change-me-to-a-long-random-secret
JWT_AUDIENCE=frame24-api
JWT_ISSUER=frame24-api
JWT_EXPIRES_IN=8h
BETTER_AUTH_SECRET=change-me-to-a-long-random-secret
BETTER_AUTH_SECRETS=change-me-old-secret,change-me-new-secret
BETTER_AUTH_URL=http://localhost:4000

Multi-Tenancy

Arquitetura multi-tenant com separação lógica de dados por empresa:

• Cada empresa possui tenant_slug único.
• Requisições são filtradas por company_id do usuário autenticado.
• Controle de acesso por papéis e permissões granulares.
• Isolamento de dados entre tenants.

Troubleshooting

Checkout no Windows

Há arquivos versionados com sufixo :Zone.Identifier dentro de mlops_project-main, que podem impedir o checkout em sistemas de arquivos Windows. A limpeza desses metadados é uma pendência de portabilidade; enquanto ela não for concluída, um checkout em sistema de arquivos Linux evita essa restrição de nomes.

Porta em uso

docker compose ps

Se necessário, ajuste portas no docker-compose.yaml e arquivos .env.

Banco não conecta

docker compose ps postgres
docker compose restart postgres

RabbitMQ indisponível

docker compose ps rabbitmq
docker compose logs -f rabbitmq

Prisma Client desatualizado

cd packages/db
pnpm db:generate
pnpm build

Deploy Docker (Coolify/VPS)

Arquivos de deploy

• dockerfile: imagem de produção da API (apps/api) com build NestJS.
• scripts/docker/api-entrypoint.sh: aplica prisma migrate deploy antes de iniciar a API.
• docker-compose.coolify.yml: stack de produção com api + postgres + minio.
• .env.coolify.example: template de variáveis para produção.

Subir na VPS com Docker Compose

cp .env.coolify.example .env.coolify
# ajuste os secrets e domínios no arquivo .env.coolify
docker compose --env-file .env.coolify -f docker-compose.coolify.yml up -d --build

Portas publicadas no host podem ser ajustadas no .env.coolify:

• API_HOST_PORT (default: 4000)
• POSTGRES_HOST_PORT (default: 5432)
• MINIO_HOST_PORT (default: 9000)
• MINIO_CONSOLE_HOST_PORT (default: 9001)

Topologia de produção recomendada:

• Coolify/VPS: api + postgres + minio.
• Redis: serviço externo gerenciado.
• RabbitMQ: serviço externo gerenciado.
• Frontends (web, admin, landing-page): hospedados na Vercel.

Atualização após novo push no main:

git pull origin main
docker compose --env-file .env.coolify -f docker-compose.coolify.yml pull api postgres minio
docker compose --env-file .env.coolify -f docker-compose.coolify.yml up -d --remove-orphans

Integração com GitHub Actions

O workflow .github/workflows/deploy.yml publica a imagem em ghcr.io/<owner>/frame-24-api e suporta dois modos:

• Coolify por webhook (COOLIFY_DEPLOY_WEBHOOK_URL).
• VPS por SSH + Docker Compose (VPS_HOST, VPS_USER, VPS_SSH_KEY, GHCR_USERNAME, GHCR_TOKEN).

No modo VPS, o limite de 1GB fica definido diretamente no docker-compose.coolify.yml via limites de memória dos serviços, distribuido entre api + postgres + minio.

Secrets recomendados no GitHub:

• COOLIFY_DEPLOY_WEBHOOK_URL (opcional, para deploy automático no Coolify)
• VPS_HOST
• VPS_USER
• VPS_SSH_KEY
• GHCR_USERNAME
• GHCR_TOKEN (PAT com read:packages)
• N8N_WEBHOOK_URL (opcional para notificação de falha)

Variáveis obrigatórias de produção

No mínimo:

• JWT_SECRET
• BETTER_AUTH_SECRET
• BETTER_AUTH_URL ou API_URL
• DATABASE_URL
• DIRECT_URL
• FRONTEND_URL (domínios Vercel permitidos por CORS, separados por vírgula)
• REDIS_URL + REDIS_HOST + REDIS_PORT (externos)
• RABBITMQ_URI + RABBITMQ_HOST + RABBITMQ_PORT + RABBITMQ_USER + RABBITMQ_PASSWORD (externos)
• MINIO_ACCESS_KEY + MINIO_SECRET_KEY + (STORAGE_PUBLIC_URL ou MINIO_PUBLIC_URL) (MinIO no VPS)

Em produção, use secrets fortes (>= 32 caracteres para JWT_SECRET e BETTER_AUTH_SECRET).

Prontidão da Fase Atual

A fase atual fecha somente quando não houver brecha crítica conhecida, os riscos médios mais perigosos tiverem owner funcional, a documentação OpenAPI refletir o comportamento real, e os fluxos críticos tiverem testes e observabilidade mínima.

Status de fechamento:

Área	Owner funcional	Status
Identity/Auth/CRM/Public	Backend/API Security + Privacy/Compliance	Segredo interno obrigatório, throttling, payload público mínimo e validação de tenant endereçados. Direitos do titular, retenção e descarte seguem como plano de compliance, sem implementação completa nesta fase.
Sales/Public/Operations	Backend/Sales + Infra/Ops	Idempotência pública, seat locking forte, cancelamento por regra temporal e throttling endereçados. Fluxos críticos precisam permanecer cobertos por testes focados.
Finance/Payments	Finance/Payments	Fora da fase atual: PIX real, webhook PSP, ledger interno, refund e chargeback não devem ser declarados como corrigidos.
Tax/Fiscal/Catalog/Stock/Contracts	Fiscal/Tax + Backend	Validação de tenant em filtros e coerência de contratos/fiscal endereçadas. Pipeline de atualização normativa e revisão fiscal completa seguem como plano fiscal.
Storage/Email/Audit/Workers	Infra/Ops + Privacy/Compliance	Auditoria com retry e DLQ endereçada. Storage por prefixo/contexto, redaction de logs e alarmes operacionais seguem como plano de observabilidade/incidente.
Marketing/Recommendations	Backend/Sales + Privacy/Compliance	Finalização de campanha/cupom sob lock transacional endereçada. Separação completa entre dados operacionais e promocionais segue como plano de privacidade.

Documentação Complementar

• API_ENDPOINTS.md
• QUICK_START.md
• FRONTEND_DEVELOPMENT.md
• FRONTEND_FILES_SUMMARY.md
• FRONTEND_FINAL_SUMMARY.md

Contribuição

1. Crie uma branch para sua feature ou correção.
2. Faça commits pequenos e descritivos.
3. Rode lint e checagem de tipos antes de abrir PR.
4. Abra um Pull Request com contexto técnico claro.

Fluxo sugerido:

git checkout -b feature/nova-feature
git commit -m "feat: adiciona nova feature"
git push origin feature/nova-feature

Licença

Projeto privado sob licença UNLICENSED.

---

Desenvolvido para o projeto de Banco de Dados da UNEB Campus 2.