📍 Origem: times/produto/cadencia/foundation/tech-architecture.md no pd-framework. Última sync: 2026-05-25.

Tech Architecture — Cadência¶

Stack consolidada do produto. Referência pra qualquer decisão técnica. Última revisão: 2026-05-25.

Esta é uma visão alto-nível. Detalhes operacionais profundos (schemas, endpoints, runbooks) vivem em ../context/ ou no repo cadencia-app/docs/.

Arquitetura macro¶

[Usuário] → [Cadência App (Next.js 15 / Vercel)]
                    ↓ proxy rewrite /api/v1/*
             [FastAPI Workers (Python 3.12 / Railway → Coolify)]
                    ↓
             [Supabase Cloud (PostgreSQL + RLS + Storage + Auth)]
                    ↓
        ┌──────────┼──────────┐
        ↓          ↓          ↓
   [OpenAI]   [Gemini]   [Playwright]
   conteúdo   capas      HTML→PNG
                    ↓
        ┌──────────┼──────────┐
        ↓          ↓          ↓
 [Resend/Svix] [Lara/Evolution] [Providers sociais]
        └──────────┼──────────┘
                   ↓
             [Blog Vercel por tenant (cadencia-blog-template)]
                    ↓
        ┌──────────┴──────────┐
        ↓                     ↓
   [Growth Pipeline       [Webhook scoring
    VPS Hostinger]        systemd]
   (cadencia-growth)

Repos GitHub¶

Frontend (cadencia-app/src/)¶

Stack: Next.js 15.5 + React 19.1 + TypeScript + Tailwind + shadcn/ui + Serwist (PWA)

Áreas (route groups): - (app)/ — app principal usuário cliente final - (admin)/ — admin interno (Felipe/equipe) - (marketing)/ — landing pages + marketing público - (onboarding)/ — Tour RPG 12 steps + provisioning - staff/ — gestão de tenants (área PD interna) - conectar-whatsapp/ — fluxo OAuth WhatsApp

API routes (src/app/api/): - app/ — endpoints app - auth/ — Supabase Auth handlers - capi/ — Meta CAPI tracking - growth/ — endpoints growth pipeline - instagram/ — Instagram OAuth + publisher - onboarding/ — fluxo onboarding - stevo/ — integração WhatsApp Stevo (multi-tenant) - v1/ — endpoints versionados - webhooks/ — webhooks externos ativos, incluindo Stripe

Lib (src/lib/): analytics, animations, api, instagram, meta-pixel, mixpanel, plans, posthog, stripe, supabase, utm

Deploy: push main → Vercel build automático.

Workers backend (cadencia-app/cadencia-workers/)¶

Stack: Python 3.12 + FastAPI + Playwright (HTML→PNG) + Dockerfile + docker-compose Coolify (railway.toml/Procfile = legado)

Pipeline 7-step orchestrator (src/workers/orchestrator.py): 1. Research Agent — pesquisa tema (Método X/Y) 2. Model Selector — classifica em 12 flags → seleciona modelo YAML (29 disponíveis) 3. Headline Agent — headline + subtitle + hook_type 4. Carousel Agent — slides JSON com componentes visuais 5. Caption Agent — legenda Instagram + hashtags 6. Cover Generation — Gemini 2.5 Flash Identity Lock ou thematic 7. Slide Renderer — Playwright HTML→PNG 1080×1440 → Supabase Storage

Agents adicionais: - caption_agent/, carousel_agent/, chat_agent/, headline_agent/, research_agent/ - dossier.py — Big5 + DPR + Kane + Archetypes - editorials.py — 3 categorias post - ideas.py — geração de ideias - instagram_publisher.py — pub IG via OAuth - logo_analysis_agent.py — análise logo - theme_agent.py — tema - visual_identity.py — VI generation - rag.py — RAG - agent_memory.py — memória dos agents - token_refresh.py — refresh tokens OAuth

Templates: 7 famílias HTML (action / editorial / engagement / narrative / proof / statement / structured) + 29 modelos YAML.

Integrations: asaas/ (legacy), llm/, pexels.py, supabase.py.

Tests: orchestrator, slide_renderer, model_selector, cover_generation, llm_client, carousel_agent, model_config, nuclear_coverage, health + visual/.

Deploy hoje: push main:master → Railway (Dockerfile + healthcheck /health). Migração ativa → Coolify VPS Master (PDL-18 a 23).

Growth pipeline (cadencia-growth/)¶

Stack: Python + Supabase + systemd (webhook handler)

Crons VPS Hostinger (crons/crontab.txt):

Pipeline (pipeline/): - blog_generate.py, seinfeld_generate.py, linkedin_generate.py, newsletter_generate.py - trigger_server.py — webhook handler systemd - backfill_images.py, brand_template.py, prompts.py

Scoring (scoring/): - cadencia-webhook.service (systemd unit) - resend_webhook.py — eventos Resend/Svix → lead scoring e supressão

Migrações Supabase (migrations/): - 001_seinfeld_scheduled_at.sql (única hoje)

Deploy hoje: /cadencia/ na VPS Hostinger (path legado). Migração ativa: /cadencia/ → /opt/cadencia-growth/ + Coolify (PDL-213, PDL-215).

Banco de dados — Supabase¶

• PostgreSQL + Row Level Security em todas as tabelas multi-tenant
• Storage segmentado por tenant (bucket tenant-photos privado, slides públicos)
• Auth magic link + senha
• Source of truth — não duplicar estado em outro lugar

Schema drift: auditado via PDL-172 (pendente). Migrations versionadas no repo cadencia-growth/migrations/ e cadencia-app/.

CRM e canais nativos¶

• Supabase é a fonte de verdade para contatos, empresas, oportunidades, pipelines, tags, scoring e cadências.
• Resend envia email transacional e de marketing; Svix autentica os eventos recebidos.
• Lara integra WhatsApp por instância Evolution e expõe agenda e tools com escopo de tenant.
• Publicação social usa o provider específico de cada canal.
• Estado compartilhado só muda após confirmação do writer ou provider responsável.

Pagamento — Stripe¶

• Migrado de Asaas em 11/05/2026 (ADR 0001)
• Asaas ainda no código integrations/asaas/ — dívida técnica (rip pendente)
• Webhooks recebidos em /api/webhooks/stripe

LLM stack (fixa — trocar exige ADR)¶

PR ativo #2: suporte a OpenRouter via OPENAI_BASE_URL/OPENAI_MODEL (workers).

Tracking & Analytics¶

Cron jobs¶

Estado ATUAL (verificado 2026-07-22, DEV-1447):

• crontab do host VPS Master (root) — pipeline growth: growth_pipeline.py (blog/seinfeld/linkedin/instagram 14h, newsletter sex 18h), cadence_tick.py (5 em 5 min), retry_provisioning.py, cleanup_orphan_ideas.py, healthcheck, advisors Supabase, drift_check. Fonte: sudo crontab -l na VPS.
• crontab do user master — cadeia PD Framework (state-aggregator 6h, deploy-watcher 10min, self-test 7h30, hostinger-watcher 8h, health-check 21h30) + conferência cobrança 21h15.
• Systemd services — cadencia-trigger.service (trigger_server porta 39090, on-demand), resend_webhook.py (@reboot), mission_control.py (@reboot).
• /api/v1/cron/rerender-slides (workers Coolify) — disparador inconclusivo. Doc antiga afirmava cron-job.org (1min interval). Investigação 2026-07-22 (DEV-1447) descartou: crontab master, crontab root, cron dentro do container, Coolify Scheduled Task, systemd, APScheduler. Logs mostram POST de 127.0.0.1 a cada ~1min — hipótese não confirmada: cron-job.org ainda ativo com IP mascarado por Traefik host-network. Interval do disparador ficou irrelevante desde DEV-1447 fix: o endpoint agora processa batch (cap 8 jobs / timeout 25s) e drena a fila inteira por call.
• /api/v1/cron/daily (workers Coolify) — mesmo endpoint pattern; disparador não verificado nesta investigação.

Não use mais como referência: "cron-job.org é o único disparador de workers". A frase está em drift desde a migração pra Coolify VPS Master (CAD-638). Cada disparo tem que ser confirmado por observação direta, não por doc.

CDN & infraestrutura externa¶

• Cloudflare — CDN
• Vercel Edge — deploy frontend + blog templates
• Railway — workers Python (migrando Coolify)
• VPS Hostinger (Master 72.60.4.71) — destino migração workers + growth pipeline

Decisões arquiteturais (ADRs formais)¶

• docs/adr/0001-stripe-em-vez-de-asaas.md — Stripe sobre Asaas (11/05/2026)

Próximas ADRs candidatas (não criadas ainda): - Multi-tenant strategy formal (hoje em foundation, mas merece ADR) - Migração Railway → Coolify (decisão arquitetural pendente formalizar) - OpenRouter vs OpenAI direto (PR #2)

Refs¶

• ../SOUL.md — princípios técnicos não-negociáveis
• tech-principles.md — 8 princípios detalhados
• multi-tenant-strategy.md — isolation profundo
• CLAUDE.md repo cadencia-app — regras operacionais técnicas
• _bmad-output/planning-artifacts/architecture.md — arquitetura detalhada BMAD