Skip to content

About

Base modular em TypeScript para aplicações web na Cloudflare, com autenticação, banco de dados, multi-tenancy, segurança e observabilidade.

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

478 Commits

Folders and files

Foundation

Base modular em TypeScript para aplicações web Cloudflare-first da t00ls-dev.
Autenticação, dados, isolamento por tenant e segurança em pacotes reutilizáveis.

CI da branch master Node.js 22.22.0 ou superior Licença MIT

Pacotes · Início rápido · Documentação · Contribuição


O Foundation reúne infraestrutura de aplicação sem regras de negócio de um produto específico. Combina React SPA e API Hono no mesmo Cloudflare Worker, com D1 como preset inicial e suporte a PostgreSQL via Drizzle.

O preset usa React Router; Levi usa navegação própria com history e estado React, preservando a mesma topologia SPA/API.

Os pacotes são internos ao monorepo, consumidos com workspace:*. O repositório inclui o Levi, aplicação privada de gestão de igrejas com domínio e banco próprios. Consulte o estado atual para entregas e pendências.

Aplicações consomem pacotes com workspace:*, mantendo versões, deploys e recursos próprios. O consumo e a validação seguem o runbook de pacotes.

Principais funcionalidades

  • Autenticação self-hosted: Better Auth com senha, verificação de e-mail, recuperação, magic link e Google OAuth opcional.
  • Multi-tenancy e autorização: contexto de tenant, memberships e convites, com permissões separadas da autenticação.
  • Dados com limites explícitos: adapters Drizzle para D1 e PostgreSQL, migrations sob responsabilidade de cada aplicação e testes reais de banco.
  • Segurança configurável: headers, CSP, CORS, CSRF, Turnstile e rate limiting.
  • E-mail, logs e auditoria: integração Resend, logging JSON contextual e eventos de auditoria append-only.
  • Qualidade automatizada: TypeScript strict, Vitest, Miniflare, Testcontainers e Playwright, incluindo cenários desktop e mobile.
  • Ferramentas no workspace: gerador basic-d1, diagnóstico read-only com Doctor e base UI compartilhada reutilizável.

Pacotes oficiais

Pacotes locais privados em packages/*:

  • @t00ls-dev/config — configuração tipada de ambiente, bancos e capabilities.
  • @t00ls-dev/db — factories Drizzle para D1 e PostgreSQL e consulta do journal PostgreSQL.
  • @t00ls-dev/auth — integração Better Auth e resolução tipada de sessão no servidor.
  • @t00ls-dev/tenant — isolamento por tenant, memberships, troca de tenant ativo e convites.
  • @t00ls-dev/access — autorização por permissões e roles configuráveis.
  • @t00ls-dev/security — proteções HTTP, Turnstile e rate limiting com storage injetável.
  • @t00ls-dev/email — contrato substituível de envio de e-mail com implementação Resend.
  • @t00ls-dev/observability — logs JSON estruturados com contexto de request, usuário e tenant.
  • @t00ls-dev/audit — eventos append-only em D1/PostgreSQL, com rejeição de chaves sensíveis na metadata.
  • @t00ls-dev/ui — componentes e padrões React privados, consumidos por fontes TSX.

Todos os workspaces são privados. Veja o consumo interno.

Requisitos

Para desenvolver neste repositório:

  • Node.js 22.23.3, patch validado pelo projeto; o mínimo declarado é >=22.22.0.
  • Corepack e pnpm 10.15.1, fixado no package.json.
  • Docker, para os testes PostgreSQL com Testcontainers.
  • Chromium e dependências de sistema, para os testes E2E com Playwright.

Instalação

Consumir um pacote

Dentro de um consumidor do workspace, adicione a dependência local:

pnpm --filter <app> add '@t00ls-dev/config@workspace:*'

Consulte os READMEs em packages/ para as APIs e requisitos de cada pacote e o guia de criação de aplicações para montar um projeto consumidor.

Preparar o repositório

git clone https://github.com/t00ls-dev/foundation.git
cd foundation
corepack enable
pnpm install --frozen-lockfile
pnpm build

O desenvolvimento local usa dependências workspace:* e não requer token privado de registry.

Início rápido

Consulte o guia do Levi para configuração e execução local. pnpm dev inicia o Levi. Para criar aplicações D1, consulte o gerador.

Para executar o gate completo, com Docker disponível:

pnpm --filter levi exec playwright install --with-deps chromium
pnpm check

Os testes usam bancos descartáveis e e-mails capturados, sem credenciais de deploy ou envio real. O runbook de testes descreve as suítes e os checks focados.

Documentação

Acessibilidade

Consulte a declaração de acessibilidade para objetivos, avaliações existentes e como comunicar barreiras.

Contribuição

Issues e pull requests focados são bem-vindos. Leia CONTRIBUTING.md para os padrões de contribuição, validação e integração. Mudanças nos pacotes são validadas junto aos consumidores locais.

Segurança

Para comunicar vulnerabilidades, siga SECURITY.md. Não exponha detalhes exploráveis, credenciais ou dados pessoais em issues públicas.

Licença

O código próprio é distribuído sob a licença MIT, com copyright de 2026 da t00ls-dev. Licenças e avisos de terceiros permanecem vigentes; consulte licenças e distribuição.

About

Base modular em TypeScript para aplicações web na Cloudflare, com autenticação, banco de dados, multi-tenancy, segurança e observabilidade.

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

0 stars

Watchers

0 watching

Forks

Used by

Contributors

Languages