devfactory-apps-docs

Site de documentação da plataforma Dev Factory, sempre publicado em

Markdown · 228 arquivos HTML · 7 arquivos JavaScript · 6 arquivos JSON · 2 arquivos 263 arquivos

Estrutura

📁 assets/7 arquivos

📁 vendor/

· auth.js

· catalog.json

· config.js

· hub.js

· styles.css

· theme-toggle.js

📁 auth/1 arquivos

· index.html

📁 docs/248 arquivos

📁 adr/

📁 apresentacao/

📁 diagramas/

📁 md/

📁 plataforma/

· 2026-06-13 devfactory-apresentacao.zip

· aws-deploy-documents-files.md

· aws-secrets-uso-local.md

· devfactory-ai-gateway.md

· devfactory-architecture.md

· devfactory-arquitetura-baas-apis.md

· devfactory-dns-route53.md

· .dockerignore

· .gitignore

· build-catalog.mjs

· index.html

· README.md

· version.json

· view.html

README

devfactory-docs

Site de documentação da plataforma Dev Factory, sempre publicado em https://docs.devfactory.space e protegido por Microsoft Entra (qualquer usuário do tenant pode ler — sem níveis de role).

A partir de agora, a documentação é feita neste repositório.

O que tem

Apresentações (decks HTML) versionadas por serviço: docs/apresentacao/plataforma/<versão> e

docs/apresentacao/servicos/<serviço>/<versão>.

Documentos .md descritivos de cada apresentação, em docs/md/... (lidos no site por um

leitor de Markdown, com link para o .md cru). A suíte técnica da plataforma está em docs/plataforma/*.md.

Diagramas draw.io (docs/diagramas) e ADRs (docs/adr).

Estrutura


index.html            hub navegável (lista plataforma + serviços + versões)
view.html             leitor de Markdown (?doc=docs/...)  — renderiza .md + link pro .md cru
auth/index.html       handler do redirect do Entra (MSAL)
assets/
  config.js           tenant/clientId do Entra
  auth.js             gate de login (MSAL); revela #content quando autenticado
  hub.js              monta a navegação a partir de catalog.json
  styles.css          design system
  vendor/marked.min.js  renderizador de Markdown (MIT)
  catalog.json        gerado por build-catalog.mjs
build-catalog.mjs     varre docs/ e (re)gera assets/catalog.json
docs/                 toda a documentação (decks, .md, diagramas, adr)

Versionamento

Pasta = versão (semver). Quando um serviço muda de versão, crie a nova pasta (docs/apresentacao/servicos/<serviço>/<nova-versão>/ + os .md em docs/md/...) e dê push — o node build-catalog.mjs roda no build da imagem (regenera assets/catalog.json), então a versão nova aparece no site após o deploy, e as antigas continuam disponíveis.

Desenvolver localmente


node build-catalog.mjs          # regenera o catálogo após mudar docs/
npx http-server -p 4173 -c-1    # servir
# abrir http://localhost:4173/?devauth=1   (bypass de login só em localhost)

Em produção (docs.devfactory.space) o ?devauth=1 não funciona — login Entra é obrigatório.

Publicar — app no EKS (igual aos outros serviços)

Este site não é mais hospedado em S3/CloudFront estático. Ele é um app containerizado (nginx) no EKS, atrás do mesmo ALB interno da plataforma, host-routed em docs.devfactory.space (CloudFront → VPC origin → ALB interno → docs-svc). O fluxo é o mesmo dos demais serviços (ver k8/dev/README-deploy.md):


# 1. build da imagem → ECR (GitHub Actions, OIDC) — dispara no push para release/dev
git push origin main:release/dev

# 2. deploy no EKS — dispara no push para release/eks/docs-dev (repo devfactory-iac)
#    aplica k8/dev/docs-deployment.yaml e reinicia docs-dev-deployment no namespace devfactory-v1-dev
git -C ../devfactory-iac push origin main:release/eks/docs-dev

Imagem: .docker/Dockerfile (multi-stage: regenera o catálogo com node build-catalog.mjs,

depois serve com nginx:alpine). ECR: devfactory-docs.

Manifesto: devfactory-iac/k8/dev/docs-deployment.yaml (Deployment + Service + Ingress

host docs.devfactory.space no grupo devfactory-dev-internal).

Auth: o gate é client-side (MSAL), no mesmo modelo do apps-console. Para proteção a nível de
arquivo (impedir download direto dos .md/decks sem login), o próximo passo é auth na borda
(validação do token Entra no ingress/edge).