Arquitectura — Portal de documentación
Visión general
Sitio estático generado con MkDocs Material que agrega la documentación de
todos los repositorios del alcance mediante mkdocs-multirepo-plugin. Se
reconstruye automáticamente ante cambios y se sirve desde Cloudflare Pages,
protegido por Cloudflare Access. No almacena contenido propio salvo su
autodocumentación: la fuente de verdad es siempre el repo de cada sistema.
Componentes
| Componente |
Responsabilidad |
Tecnología |
| Generador |
Construir el sitio estático con búsqueda en español |
MkDocs + tema Material |
| Agregador |
Clonar los repos del alcance en build time y montar sus docs/ |
mkdocs-multirepo-plugin |
| CI |
Build y deploy en cada cambio |
GitHub Actions |
| Hosting |
Servir el sitio estático |
Cloudflare Pages |
| Control de acceso |
Restringir el portal al equipo interno |
Cloudflare Access |
Dependencias externas
| Dependencia |
Uso |
¿Qué pasa si no está? |
| GitHub (repos del alcance) |
Fuente del contenido en build time |
El build falla; el sitio ya publicado sigue online |
| GitHub Actions |
Ejecutar build y deploy |
El portal deja de actualizarse; no se cae |
| Cloudflare Pages |
Hosting del sitio |
Portal inaccesible (contenido intacto en los repos) |
| Cloudflare Access |
Autenticación del equipo |
Sin acceso, o portal expuesto si se desactiva mal |
Diagrama
flowchart LR
R1[repo docs-standard] -->|push a main| GH[GitHub Actions]
R2[repo oms-backend] -->|repository_dispatch| GH
R3[otros repos...] -->|repository_dispatch| GH
P[repo docs-portal] -->|push a main| GH
GH -->|mkdocs build + multirepo import| S[sitio estático]
S -->|wrangler pages deploy| CF[Cloudflare Pages]
CF --> A[Cloudflare Access]
A -->|equipo interno| U[docs.compulandia.com.py]
Flujo principal
- Un desarrollador mergea a
main en cualquier repo del alcance.
- Un workflow mínimo en ese repo dispara un
repository_dispatch
(evento docs-update) hacia docs-portal.
- GitHub Actions del portal ejecuta
mkdocs build: el plugin multirepo clona
cada repo del nav: y monta su carpeta docs/.
- El sitio resultante se publica en Cloudflare Pages con
wrangler.
- Cloudflare Access valida la identidad del visitante antes de servir.