9-11/adding-content

.github/workflows/ci.yml

@@ -1,5 +1,45 @@
 name: CI
 
+on:
+  push:
+    branches: [ dev, main ]
+  pull_request:
+    branches: [ dev, main ]
+
+jobs:
+  build-and-test:
+    name: Build and Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'yarn'
+
+      - name: Install dependencies
+        run: |
+          corepack enable
+          corepack prepare yarn@stable --activate
+          yarn install --frozen-lockfile
+
+      - name: Run build
+        run: yarn build
+
+      - name: Run tests (node --test scripts)
+        run: yarn test
+
+      - name: Upload build artifacts (optional)
+        if: success()
+        uses: actions/upload-artifact@v4
+        with:
+          name: site-build
+          path: build
+name: CI
+
 on:
   pull_request:
     # run on PRs targeting main branches used in this repo

.mona/CODEBASE_ANALYSIS.md

@@ -0,0 +1,99 @@
+## Análise do Codebase — MonaDocs
+
+Autor: AI assistant (análise automatizada)
+Data: 2025-11-09
+
+Resumo executivo
+-----------------
+
+Este repositório é um site de documentação construído com Docusaurus v3. A estrutura é clara e segue convenções típicas de sites de docs: pasta `docs/` para conteúdo, `blog/` para posts, `src/components/` para componentes React reutilizáveis, e `static/` para ativos estáticos. O projeto requer Node >= 20 e usa `yarn` como gerenciador. O objetivo deste documento é registrar padrões, convenções e recomendações acionáveis.
+
+Contrato da análise (inputs/outputs)
+-----------------------------------
+- Inputs: código-fonte do repositório (arquivos principais lidos: `package.json`, `docusaurus.config.js`, `sidebars.js`, `README.md`, `docs/intro.md`).
+- Output: este arquivo de análise com padrões identificados, riscos e recomendações.
+- Critério de sucesso: documento legível e acionável, cobrindo stack, arquitetura, convenções de docs e sugestões práticas.
+- Modos de falha esperados: arquivos ausentes/inconsistentes (não ocorreu), referências a runtime de browser no SSR (risco comum e documentado abaixo).
+
+Resumo técnico e stack
+----------------------
+- Framework: Docusaurus v3 (preset `classic`).
+- Node: engines.node >= 20.
+- Package manager: yarn (scripts no `package.json`).
+- React: 19.x (dependência declarada).
+- MDX/MD: suporte via `@mdx-js/react` e arquivos `.md` / `.mdx` em `docs/` e `blog/`.
+- Syntax highlighting: `prism-react-renderer`.
+
+Estrutura e padrões observados
+------------------------------
+- `docusaurus.config.js`: configura navbar, footer, presets, i18n (apenas `en` configurado) e opções de build. `editUrl` aponta para a branch `dev` no GitHub.
+- `sidebars.js`: gerador programático de sidebar. Padrão:
+  - TOP_FOLDERS explícito: `['projects','repositories','technologies','guidelines','identity','contribution','architecture']`.
+  - Lógica: lê `docs/<folder>`; prioriza `index.md`/`index.mdx`; deduplica entradas e ordena (index primeiro, depois alfabético).
+  - Usa `_category_.json` quando presente para rótulos e descrições.
+- Docs: estrutura por subpastas (projects, technologies, etc.). Convenção recomendada observada: ter apenas um `index.md`/`index.mdx` por pasta.
+- Componentes: `src/components/` armazena componentes reusáveis usados nas páginas/MDX (ex.: `HomepageFeatures`, `Repositories`, `TechStack`).
+
+Padrões de desenvolvimento e riscos conhecidos
+-------------------------------------------
+- SSR vs browser APIs: o README e o código alertam para não usar `window`/`localStorage` diretamente em arquivos que executam em SSR (config e sidebars rodam em Node). A prática certa (já mencionada no README) é acessar APIs de browser dentro de `useEffect` ou com `typeof window !== 'undefined'`.
+- Duplicidade de documentação: ter `index.md` e `index.mdx` na mesma pasta pode gerar entradas duplicadas na sidebar. `sidebars.js` tenta deduplicar, mas é melhor manter um único arquivo índice por pasta.
+- Componentes que fazem fetch (ex.: `Repositories`) usam cache em localStorage com TTL — atenção a rate limits e comportamento em CI/SSG (deve haver fallback gracioso quando não autorizado ou em ambiente sem `window`).
+
+Scripts e fluxo de desenvolvedor
+--------------------------------
+- scripts principais (`package.json`):
+  - `start` -> `docusaurus start` (dev server)
+  - `build` -> `docusaurus build`
+  - `serve` -> `docusaurus serve` (preview da build)
+  - `deploy` -> `docusaurus deploy` (GitHub Pages)
+  - `favicon:generate` -> `node scripts/generate-favicons.js`
+  - `test` -> `node --test scripts`
+- Observação: `test` executa testes via Node e `scripts/` contém alguns testes utilitários (`homepage.test.js`). Não há um pipeline de CI padronizado no repositório (a ser recomendado).
+
+Conveções de conteúdo (docs/blog)
+---------------------------------
+- Uso de `_category_.json` para metadados de categoria na pasta `docs/`.
+- Nomes de arquivos/URLs: usar `YYYY-MM-DD-title.md` para posts e frontmatter para metadata no blog.
+- Imagens locais para docs: conventiona é colocar imagens dentro da pasta da seção e referenciar como `./img/foo.png` quando aplicável.
+
+Observações sobre configuração dinâmica do sidebar
+-------------------------------------------------
+- O `sidebars.js` é programático e depende de `TOP_FOLDERS`. Isso facilita organização automática, mas:
+  - Fornece menos controle manual sobre ordem fina dentro de categorias; para casos especiais pode-se substituir por uma sidebar manual para aquela categoria.
+  - Mudanças estruturais em `docs/` podem alterar a sidebar automaticamente — bom para produtividade, exige revisão de PRs que mexam em pastas.
+
+Recomendações (priorizadas)
+---------------------------
+1) Adicionar CI básico (GitHub Actions) que execute:
+   - `yarn` e `yarn build` (garante que o site constrói em Node >= 20)
+   - `yarn test` (executa `node --test scripts`)
+   - um passo opcional de checagem de links (link checker) e checagem de acessibilidade básica.
+2) Adicionar linter/formatador (ESLint + Prettier) nas partes de JS/TS/MDX para consistência e evitar erros de runtime (ex.: uso inadvertido de APIs de browser).
+3) Criar arquivo `CODEOWNERS` ou documento de manutenção (quem aprova PRs por área: docs, components, infra).
+4) Documentar claramente no README/CONTRIBUTING as regras de SSR e patterns para components (ex.: usar `useEffect` para localStorage). Link para exemplos.
+5) Padronizar um único `index.md`/`index.mdx` por pasta e adicionar uma checagem de CI que falhe quando detectar ambos (script simples que procura pares duplicados).
+6) Opcional: adicionar um pequeno smoke test Playwright/puppeteer que carregue a rota `/` e confirme 200/markup básico após `yarn build`.
+
+Edge cases e riscos
+-------------------
+- Ambientes de build sem `window` (SSG) — componentes que acessam localStorage sem guarda podem quebrar `yarn build`.
+- Limites de API ao consumir GitHub public endpoints sem autenticação — componentes devem degradar graciosamente.
+- Mudanças automáticas na estrutura de `docs/` podem alterar a ordem do sidebar inesperadamente; rever PRs que adicionem pastas.
+
+Próximos passos sugeridos (curto prazo)
+-------------------------------------
+1. Merge deste arquivo em `.mona` (feito). Use-o como ponto de referência para PRs sobre infra.  
+2. Criar workflow GitHub Actions mínimo (build + test + link-check).  
+3. Adicionar `CONTRIBUTING.md` com checklist rápido (build local, lint, testes manuais).  
+4. Implementar checagem simples para duplicação index.md/index.mdx em CI.
+
+Referências (arquivos lidos)
+---------------------------
+- `package.json` — scripts, engines, dependências.  
+- `docusaurus.config.js` — configuração global (navbar, footer, presets, theme).  
+- `sidebars.js` — gerador dinâmico de sidebar; TOP_FOLDERS e lógica de leitura.  
+- `README.md` — instruções de dev, build e deploy, boas práticas e pitfalls.  
+- `docs/intro.md` — exemplo de conteúdo e frontmatter.
+
+Fim da análise.

docs/architecture/architecture-rationale.md

@@ -0,0 +1,56 @@
+## Architecture Rationale & Tradeoffs
+
+Purpose
+-------
+This short document explains the rationale and tradeoffs behind the primary architecture choices in the Monynha platform. It is intended for engineers and architects who need to make consistent design decisions across products.
+
+1. Node.js + TypeScript (API layer)
+----------------------------------
+- Rationale: Node.js provides fast developer iteration, broad ecosystem, and excellent support for JSON-first APIs. TypeScript enforces type-safety and reduces runtime bugs, especially in a polyglot team.
+- Tradeoffs: Node's single-threaded model requires careful handling of CPU-bound tasks. For heavy background processing, we recommend offloading to worker processes (e.g., AWS Fargate tasks, serverless functions, or a dedicated worker pool in Go/Java).
+- When to choose otherwise: Use a compiled language (Go, Rust) when strict latency, lower memory footprint, or predictable concurrency are top priorities.
+
+2. PostgreSQL + Prisma (Primary Data Store)
+-------------------------------------------
+- Rationale: PostgreSQL is battle-tested, supports complex queries, transactional integrity, and is well-supported by managed services (RDS, Supabase). Prisma provides productivity gains (type-safe client, migrations).
+- Tradeoffs: Prisma's generated client increases build-time and requires careful migration sequences for large schemas. For extremely large-scale, consider a more explicit SQL-first approach and careful indexing strategies.
+
+3. Supabase for Realtime & Storage
+----------------------------------
+- Rationale: Supabase provides a convenient, integrated feature set (Realtime, Auth, Storage) that accelerates MVP and prototype development.
+- Tradeoffs: Vendor lock-in risk and feature limits for enterprise workloads. For long-term scale, plan migration paths (e.g., replace Realtime with Redis Streams / WebSockets; replace Auth with self-hosted OIDC provider).
+
+4. Client-Side Persistence (localStorage for web apps)
+---------------------------------------------------
+- Rationale: For offline-first UX and low-infrastructure MVPs, localStorage provides immediate persistence with zero server cost.
+- Tradeoffs: localStorage is not secure for sensitive data and has size limits (~50MB). For multi-device sync and scale, migrate to a backend store (Firestore, Postgres with WebSockets) and implement robust conflict resolution.
+
+5. Monorepo (Turborepo) vs Multi-Repo
+-------------------------------------
+- Rationale: Monorepo simplifies cross-project changes, version alignment, and shared tooling. Turborepo (or equivalent) provides caching and task orchestration.
+- Tradeoffs: Requires CI investment (caching, focused builds) and governance around package boundaries. If teams grow into many independent products, evaluate splitting into smaller repos or a hybrid approach.
+
+6. Containerization & Orchestration
+-----------------------------------
+- Rationale: Containers (Docker) + orchestrators (ECS/Fargate) deliver portability and predictable deployments for services.
+- Tradeoffs: Orchestration adds operational complexity. For small services, serverless functions (AWS Lambda) may be more cost-effective.
+
+Operational guidance & patterns
+------------------------------
+- Observability: instrument APIs with structured logs (JSON), distributed tracing (OpenTelemetry), metrics (Prometheus) and alerts (PagerDuty/Teams).
+- Backups & DR: schedule regular logical backups for Postgres and test restores periodically. Store immutable backups offsite.
+- Security: enforce least-privilege IAM roles and rotate secrets regularly. Use a secrets manager (AWS Secrets Manager / HashiCorp Vault).
+- Cost control: use autoscaling with sensible minimums and on-demand scheduled scaling for predictable traffic.
+
+Decision checklist (quick)
+-------------------------
+Before adopting a new technology, answer:
+1. Does it reduce developer time-to-value significantly?  
+2. Are there production-grade libraries and community support?  
+3. Is operational cost and complexity acceptable?  
+4. Is there a clear migration or rollback plan?  
+
+Links & references
+------------------
+- Architecture discussions and RFCs: `docs/architecture/rfcs/` (create RFCs there for major changes).
+- Observability starter: `docs/operations/observability.md` (recommended next addition).

docs/architecture/ci-cd-advanced.md

@@ -0,0 +1,64 @@
+## Advanced CI/CD Patterns
+
+This page documents advanced CI/CD patterns recommended for the Monynha monorepo. It complements `ci-cd.md` by providing operational recipes, secrets handling, remote caching guidance, and release strategies suitable for experienced engineers.
+
+1) Secrets & Credentials Management
+----------------------------------
+- Store secrets in a dedicated secrets manager (GitHub Actions Secrets for short-lived values; AWS Secrets Manager or HashiCorp Vault for production secrets). Do not store secrets in repo or artifacts.
+- Rotate secrets on a regular schedule; implement automated rotation for short-lived tokens where possible.
+- Example pattern (GitHub Actions + AWS Secrets Manager):
+  - CI reads short-lived deploy token from AWS Secrets Manager using an IAM role with limited scope.
+  - The role is provided to the runner via OpenID Connect (OIDC) to avoid long-lived credentials.
+
+2) Reproducible Builds & Artifact Signing
+----------------------------------------
+- Use lockfiles (`yarn.lock`, `pnpm-lock.yaml`) and pinned base images to ensure reproducible builds.
+- Produce signed artifacts: sign Docker images (cosign) and generated JS/CSS bundles where applicable. Store signatures alongside artifacts in registry.
+- Example: build → cosign sign ghcr.io/<repo>/web:<sha> → push signature to OCI registry.
+
+3) Remote Caching for Monorepo (Turborepo)
+------------------------------------------
+- Enable remote caching in CI so repeated builds only run changed tasks. Use an S3-compatible bucket or remote cache service.
+- Cache keys should include Node version, lockfile checksum, and repo SHA to avoid cache poisoning.
+- Example turbo.json snippet:
+
+```json
+{"pipeline": {"build": {"cache": true}}}
+```
+
+4) Test Matrices & Isolation
+----------------------------
+- Split tests into lightweight unit tests (fast), integration tests (database-backed), and E2E (slow). Run unit tests on every PR and gate integration/E2E on merge to main or on demand.
+- Use ephemeral databases (Postgres containers) and separate credentials per workflow run to avoid state bleed.
+
+5) Preview Environments & PR Previews
+------------------------------------
+- Deploy preview builds for PRs using a hosting provider (Vercel, Netlify) or ephemeral environments on Kubernetes/ECS.
+- Provide a bot comment with the preview URL; include an automated accessibility and Lighthouse report for each preview.
+
+6) Deployment Strategies & Rollbacks
+-----------------------------------
+- Blue/Green or Canary deployments are preferred for services with live traffic.
+- Implement health checks and automated rollback: if new deployment fails health checks, rollback to the previous revision automatically.
+- Store deployment metadata and release tags to facilitate rollbacks and audits.
+
+7) Secrets for Third-Party Integrations
+--------------------------------------
+- When integrating with external providers (Clerk, Firebase, payment gateways), treat their API keys as secrets and scope them to the minimum necessary privileges.
+- Prefer server-side proxies for sensitive operations and keep frontend keys public-only where intended.
+
+8) Observability & CI Signals
+-----------------------------
+- Fail CI on: lint/type-check failures, unit test regressions, critical vulnerability scans (high/critical), bundle-size increases beyond threshold.
+- Record CI metrics (build time, test duration, failure rates) and use them for performance SLAs on developer productivity.
+
+9) Governance & Change Control
+------------------------------
+- For infra changes (Terraform, deployment scripts), require at least two approvals and run `terraform plan` in CI, posting plan output to the PR for review.
+- Automate drift detection and schedule regular infra audits.
+
+References & recipes
+--------------------
+- OIDC with GitHub Actions: https://docs.github.com/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect
+- cosign for image signing: https://github.com/sigstore/cosign
+- Turborepo remote caching: https://turborepo.org/docs/features/remote-caching