Whitepaper & Trust Center (A9)

whitepaper de arquitetura agility — plataforma de gestão ágil de projetos central it · agility v2 · whitepaper de arquitetura arquitetura técnica, isolamento por tenant, identidade, dados, integrações, auditoria, segurança da informação e implantação central it · artefato a9 · v1 0 autor tech writer — central it empresa responsável central it tecnologia da informação s/a data de emissão 24 de setembro de 2026 versão do artefato 1 0 público alvo arquitetura, segurança, infraestrutura, operação, auditoria e avaliadores técnicos de clientes enterprise/governo uso externo controlado este whitepaper foi preparado para apoiar avaliações formais de arquitetura e segurança do agility em processos de venda enterprise e contratação pública não descreve dados de cliente específico, credenciais, endpoints internos, portas de serviço, urls de repositório privado, variáveis de ambiente ou identificadores operacionais controle do documento versão data autor descrição 1 0 24/09/2026 tech writer — central it whitepaper de arquitetura do sistema agility v2, primeira emissão base documental consultada este whitepaper foi elaborado a partir da leitura direta do código fonte e da documentação técnica publicada dentro do próprio repositório do agility v2, sem depender de material comercial de terceiros as fontes consultadas foram código fonte da api em go, incluindo pacotes de autenticação, resolução de tenant, persistência, integrações e camadas http migrações canônicas do banco de dados relacional em `api/migrations/`, com o baseline e ajustes evolutivos runbooks operacionais publicados em `docs/operators/` (entrega, iam, banco por tenant, integração de forge, recurso de ia por tenant, diagnóstico e recuperação) registros de decisão arquitetural em `docs/adr/` (do adr 0001 ao adr 0022), utilizados como âncora para as escolhas descritas glossário canônico do produto em `docs/glossary md` ficha de icp e mensagem central do agility (artefato a0, v2), utilizada para alinhamento de vocabulário e definição de categoria de produto 1\ introdução este documento apresenta a arquitetura do sistema agility — plataforma de gestão ágil de projetos — considerando seus principais componentes funcionais, técnicos, integrações, mecanismos de autenticação e autorização, camadas de dados, isolamento por tenant, rastreabilidade, implantação e controles de segurança aplicáveis ao escopo analisado o objetivo é fornecer uma visão clara e auditável da solução, demonstrando como o agility organiza a entrega de trabalho (workspaces, projetos, times, boards, arts, portfólios) sobre uma base multi tenant fisicamente isolada e integrada ao ecossistema de plataforma da central it este documento não descreve chaves, senhas, endpoints internos de infraestrutura, portas de serviço internas, variáveis de ambiente sensíveis nem lista nominal de colaboradores também não substitui o acordo de nível de serviço (artefato a3) nem as condições comerciais vigentes 2\ sumário executivo o agility foi concebido como uma plataforma corporativa para gestão ágil de projetos, cobrindo desde o cartão isolado de um kanban até estruturas safe completas com portfólios, agile release trains (arts), planning intervals (pis), times e métricas de fluxo o modelo suporta kanban, scrum, tradicional e safe sob o mesmo núcleo, com capacidades habilitadas por projeto a arquitetura se apoia em uma api escrita em go, uma single page application em react empacotada e embutida no próprio binário da api, e uma malha de resolução multi tenant operada pelo componente tenancit da plataforma cada tenant recebe seu próprio banco relacional postgresql e seu próprio bucket de armazenamento de objetos minio autenticação é delegada a keycloak por tenant, com o principal agility reconstruído a partir de qualquer credencial suportada as integrações externas cobrem provedor de identidade (keycloak), armazenamento de objetos (minio), forge git por tenant (gitlab), assistente de estimativa por ia por tenant e integração de leitura contra o erp corporativo, sob a premissa de que fatos financeiros confirmados pelo erp não são editados a partir do agility multi tenant com isolamento físico por database e por bucket identidade federada por keycloak, com resolução por host spa embarcada no binário da api, entregue sob path público único migrações versionadas com trava distribuída e ledger próprios trilha de versões (history) uniforme por espécie de entidade contratos http e serviços de domínio testados de ponta a ponta 3\ contexto e motivação a gestão de projetos ágeis em organizações que rodam múltiplos projetos em paralelo enfrenta os mesmos pontos recorrentes baixa visibilidade do que está em andamento, dificuldade para priorizar backlog, falta de indicadores confiáveis sobre prazos e capacidade, e fragmentação de identidade e dados entre produtos internos que precisam conversar o agility responde a esse cenário oferecendo uma plataforma única que acompanha kanban, scrum, tradicional e safe sob a mesma raiz de workspace, integrada nativamente ao restante do ecossistema da central it (keycloak, tenancit, hyper platform e, quando presente, itsm corporativo) a motivação arquitetural é organizar os componentes da solução de forma segura, rastreável e operacionalmente implantável em modelo multi tenant, com isolamento físico de dados por cliente e superfície pública única de entrega 4\ objetivos da arquitetura definir uma visão técnica consolidada dos componentes do agility demonstrar como a solução organiza autenticação, autorização e capabilities de projeto mapear repositórios de dados, artefatos binários, forge git por tenant e assistentes de ia opcionais registrar integrações externas relevantes e seus impactos na arquitetura, com destaque para a leitura contra o erp corporativo descrever mecanismos de auditoria, histórico uniforme e rastreabilidade transversais indicar requisitos técnicos mínimos para implantação, operação e suporte em ambiente multi tenant apresentar limitações conhecidas e pontos que dependem de definição complementar por infraestrutura ou por política de cliente servir como referência para arquitetura, segurança, infraestrutura, operação, governança e auditoria 5\ escopo da solução dentro do escopo arquitetura lógica e funcional do agility (api, spa, migrações) modelo multi tenant e isolamento físico por banco e por bucket camada de identidade federada por keycloak por tenant camada de dados postgresql com schema fixo `agility` e migrações canônicas versionadas camada de armazenamento de objetos minio por tenant integrações externas forge git por tenant, assistente de ia por tenant e leitura contra o erp corporativo trilha de versões (history) e log de auditoria funcional e técnica contrato de entrega em docker, imagem publicada em registro corporativo, helm chart, e path público único por instalação fora do escopo deste documento chaves, senhas, tokens, dsns, cookies, client secrets, endpoints internos de infraestrutura e portas de serviço lista nominal de pessoas, tenants de clientes específicos, credenciais operacionais e urls privadas condições comerciais, sla e política de uso justo, que vivem em seus próprios artefatos detalhamento de tela por tela, que pertence ao manual do usuário 6\ visão geral da arquitetura a arquitetura do agility organiza se em camadas apresentação, api, domínio, dados, integrações, identidade, resolução multi tenant, auditoria e operação a interface é uma spa em react (build com vite/bun) empacotada em pacote estático e embutida no binário da api em go o usuário acessa o produto por um path público único configurado por instalação, com gateway que encaminha rotas de dados para o processo go e demais recursos para a spa embarcada a autenticação e autorização são apoiadas por keycloak, configurado por tenant a resolução multi tenant é feita pelo componente tenancit da plataforma cada requisição chega com um host, e o tenancit devolve o tenant identificado e os recursos que ele publica (banco, storage, idp, forge, ia) recursos são resolvidos por alias no padrão `agility \<recurso>` e nunca compartilhados entre tenants a persistência utiliza postgresql com um database por tenant, cada um contendo exclusivamente o schema fixo `agility` migrações são aplicadas por goose com trava distribuída e ledger próprios o armazenamento de arquivos utiliza minio com um bucket por tenant 7\ componentes técnicos componente descrição responsabilidade arquitetural usuário / navegador ponto de acesso da solução web permitir interação com boards, backlogs, planejamento safe, dashboards e ações conforme perfil e capabilities do projeto spa agility (react) camada de apresentação escrita em react (vite + bun), embutida em pacote estático dentro do binário da api renderizar workspaces, projetos, times, boards, backlogs, portfólios, arts, pis, dashboards e superfícies de governança api agility (go) serviço http em go, roteador chi, expõe rotas `/v1/ `, `/healthz`, `/readyz` e serve a spa embutida implementar autenticação, autorização por capability, domínio de projetos, execução, planejamento, finanças, governança, integrações e histórico tenancit plano de controle multi tenant da plataforma, resolve host → tenant e devolve recursos por alias identificar o tenant chamador, publicar recursos (banco, storage, keycloak, gitlab, ia) e garantir que a resolução falhe fechada em caso de erro keycloak provedor de identidade federado, um resource `agility keycloak` por tenant, sem client global emitir e validar tokens oidc, expor client de login e client de diretório com escopo mínimo (`view users`, `query users`) postgresql por tenant um database por tenant, com schema fixo `agility` persistir workspaces, projetos, boards, backlogs, arts, pis, portfólios, finanças, histórico e configurações minio por tenant bucket exclusivo por tenant, resolvido via alias `agility minio` armazenar anexos, documentos e artefatos vinculados aos projetos, com isolamento físico entre tenants adapter erp adapter http contra o erp corporativo, contrato publicado como `sdk/specs/{registry,finance,costing} json` ler projetos, parceiros, posição de tesouraria, centros de custo, títulos e saldo de orçamento sob allow list estrita de operações adapter gitlab (forge por tenant) cliente git corporativo por tenant, alias `agility gitlab` habilitar integração de forge por tenant sem acoplar o produto a um gitlab global assistente de ia recurso opcional por tenant, resolvido via alias `agility ai` prover estimativa auxiliar de story points e prazos, com trilha de auditoria específica (`ai estimate audit`) migrações goose sequência canônica em `api/migrations/`, aplicada com trava distribuída e ledger próprios manter o schema `agility` alinhado ao código em todos os tenants, com ordem determinística e rastreio de aplicação trilha de histórico pacote de domínio `history`, append only, snapshot por espécie de entidade registrar quem mudou, quando, e do que para o que, sobrevivendo ao hard delete e uniforme entre agregados logs de auditoria registros técnicos e funcionais em ledger próprio e trilhas específicas garantir rastreabilidade de decisões de autenticação, resolução de tenant, migrações e ações de negócio relevantes 8\ diagrama de referência o diagrama abaixo apresenta uma visão conceitual dos principais componentes e fluxos do agility em modelo multi tenant a representação deve ser validada com a arquitetura final de infraestrutura, rede e operação antes de uso como evidência definitiva usuário/navegador │ (https, path público único) ▼ gateway/ingress ── path público /\<app base> │ ├──▶ spa agility (react, embarcada no binário) │ └──▶ api agility (go, chi router) │ ├──▶ tenancit ── resolve host → tenant + recursos │ ├──▶ keycloak (agility keycloak, por tenant) │ ├──▶ postgresql (agility postgres, por tenant, schema fixo) │ ├──▶ minio (agility minio, por tenant, bucket exclusivo) │ ├──▶ gitlab (agility gitlab, por tenant, opcional) │ ├──▶ ia (agility ai, por tenant, opcional) │ └──▶ erp corporativo (leituras curadas, app key + tenant externo) figura 1 — visão conceitual da arquitetura lógica do agility 9\ arquitetura lógica da solução o usuário acessa o agility por https no path público único configurado por instalação o gateway/ingress encaminha as rotas de dados (`/v1/ `, `/healthz`, `/readyz`) para o processo go e o restante para a spa embarcada a api valida a credencial recebida (token oidc do keycloak, token da plataforma ou token de desenvolvimento, quando explicitamente habilitado) e reconstrói o principal do agility o caminho da credencial fica registrado no principal, mas não vaza para os handlers o tenancit é consultado para resolver o host da requisição em um tenant e trazer os recursos habilitados (banco, storage, idp, forge, ia) em caso de erro, a resolução falha fechada e a chamada é rejeitada os serviços de domínio (`api/internal/service/ `) executam a regra de negócio (project, board, planning, portfolio, art, scrum, kanban, finance, execution, governance, risk, reporting, integration, aiadvisor, entre outros) os dados de negócio são persistidos no postgresql do tenant, no schema fixo `agility` arquivos e anexos vão para o bucket minio exclusivo do tenant integrações externas (erp, gitlab, ia) são acionadas por adapters, sob configuração por tenant e allow list explícita eventos funcionais relevantes geram trilha de histórico (por entidade) e registros de auditoria técnica quando aplicável 10\ camada de apresentação e deploy a spa do agility é construída em react sobre vite com bun, e empacotada como conjunto de arquivos estáticos embutidos no binário da api um único artefato de imagem é publicado no registro corporativo e entregue via helm chart sob o path público único, o gateway encaminha rotas de dados ao processo go e as demais rotas à spa item configuração prevista aplicação serviço `agility` (service, deployment e ingress com o mesmo nome no namespace de plataforma) modelo de entrega imagem de contêiner única publicada em registro corporativo path público path base único por instalação; o vite espelha o mesmo base path, incluindo cliente hmr nos ambientes de desenvolvimento hosted rotas de dados `/v1/ `, `/healthz` e `/readyz` são encaminhadas ao processo go rotas de ui demais rotas são atendidas pela spa embarcada migrações aplicadas pelo binário `migrate` (goose) com trava distribuída e ledger próprios ci/cd pipeline em gitlab com estágios `test`, `build` e `deploy`; workflow explicita eventos válidos (merge request, branch padrão, tag ou disparo manual) modelo de entrega único a spa é embutida no mesmo binário que atende a api isso elimina a superfície de deploy separada para o front end e garante que qualquer versão da api sirva exatamente a spa compatível daquele build 11\ camada de dados a camada de dados adota um database postgresql por tenant, resolvido dinamicamente pelo tenancit por alias `agility postgres` o schema aplicacional é fixo (`agility`) e não é configurável por tenant — o próprio código valida a `search path` no início das migrações e falha explicitamente caso a resolução não atenda ao contrato recurso alias finalidade banco de dados relacional agility postgres persistência principal do agility workspaces, projetos, times, boards, backlogs, arts, pis, portfólios, finanças, histórico, configurações e trilhas armazenamento de objetos agility minio armazenamento de anexos, documentos e artefatos vinculados a cards, projetos e portfólios um bucket por tenant provedor de identidade agility keycloak autenticação federada por tenant e diretório de usuários forge git (opcional) agility gitlab integração de forge por tenant, quando habilitada assistente de ia (opcional) agility ai assistente de estimativa por ia por tenant, quando habilitado migrações canônicas vivem em `api/migrations/` e são aplicadas pelo binário `migrate` em ordem determinística, com trava distribuída (`migrationlock`) e ledger de aplicação (`migrationledger`) migrações declaradas para todos os tenants podem ser aplicadas pelo binário `migrate tenants`, que percorre a lista de tenants conhecidos e aplica a mesma sequência em cada banco isolamento físico por tenant não existe compartilhamento de banco, bucket, tabela ou linha entre tenants a resolução por host produz recursos exclusivos daquele tenant, e uma resolução que falhe rejeita a requisição em vez de servir dado de outro contexto 12\ autenticação, autorização e permissionamento a solução utiliza keycloak como provedor de identidade, configurado por tenant cada tenant publica no tenancit um recurso `agility keycloak` com o client de login próprio, a audiência esperada, a credencial daquele client e um client administrativo de diretório com escopo mínimo não existe client global e não existe credencial de fallback a api aceita três origens possíveis de credencial e reconstrói o mesmo `principal` a partir de qualquer uma delas — os handlers nunca aprendem qual delas foi usada as origens suportadas são token oidc do keycloak, verificado contra o realm daquele tenant, com o `audience` esperado token de plataforma emitido para o app shell autorizado (fluxo hosted), aceito como cookie ou credencial `bearer` token opaco de desenvolvimento local, aceito somente quando explicitamente habilitado por variável de ambiente; a api recusa subir sem um modo de autenticação declarado a autorização é feita por `capability` no escopo do tenant/projeto, com cinco valores canônicos `view`, `comment`, `edit`, `approve` e `admin` uma capability é verificada antes de qualquer ação sensível; o menor privilégio é a regra padrão além disso, cada projeto publica uma lista derivada de capabilities de superfície (por exemplo `board`, `backlog`, `wbs`, `gantt`, `finance`) que decide quais visões estão habilitadas — esconder uma capability não apaga o dado por trás dela, só remove a superfície de acesso controle aplicação na arquitetura autenticação identificação do usuário por credencial aceita (oidc do keycloak, token da plataforma ou dev token quando habilitado) autorização verificação de capability antes de qualquer ação sensível, no escopo de tenant/projeto resolução multi tenant host → tenant → recursos, sempre pelo tenancit, com falha fechada em caso de erro tokens oidc/jwt com audiência declarada e provedor identificado por fingerprint interno auditoria registro de tentativas de autenticação, resolução de tenant e eventos de segurança menor privilégio client de diretório com escopo `view users`/`query users`, sem admin global 13\ perfis e personas o agility foi desenhado para atender múltiplas personas corporativas a superfície visível a cada usuário é derivada da capability no projeto e das capabilities habilitadas por aquele projeto (por exemplo, `finance` só aparece em projetos com esse eixo) a tabela abaixo consolida as personas identificadas no material de posicionamento e no glossário canônico do produto perfil / persona objetivo de uso membro de time executar o próprio backlog em board de kanban ou scrum, movimentar cards, registrar horas e anexos product owner / analista manter backlog, priorizar stories, acompanhar sprint ou fluxo kanban scrum master / coach ágil acompanhar cadência, wsjf, wip, impedimentos e inspect & adapt gerente de projeto (tradicional) planejar wbs, gantt, dependências e marcos, quando o projeto é do tipo tradicional time safe / rte coordenar art, pi, iterações, objetivos, capacidade, prontidão, riscos e ações de melhoria pmo / governança consolidar múltiplos projetos, ver portfólios, metas, requisitos e indicadores agregados financeiro de projeto acompanhar orçamento consumido e disponível, com referência ao erp corporativo administrador de workspace configurar workspace, membership, times, arts, portfólios e capabilities dos projetos 14\ integrações externas as integrações do agility são conservadoras sempre por adapter dedicado, sempre configuráveis por tenant, sempre com allow list explícita as integrações relevantes hoje são integração finalidade arquitetural observação keycloak autenticação federada por tenant um resource `agility keycloak` por tenant; sem client global; audiência declarada minio armazenamento de objetos por tenant um bucket exclusivo por tenant; isolamento físico espelha o modelo de banco por tenant gitlab (forge por tenant) integração de forge git por tenant, quando habilitada token e webhook secret nunca são serializados; alias `agility gitlab` assistente de ia (por tenant) estimativa auxiliar de story points e prazos opcional; alias `agility ai`; toda decisão do usuário é auditada em `ai estimate audit` erp corporativo leitura de projetos, parceiros, posição de tesouraria, centros de custo, títulos e saldo de orçamento contrato curado publicado como `sdk/specs/{registry,finance,costing} json`; app key com escopo `read finance`, `read costing` e `read registry`; fatos financeiros do erp não são editados a partir do agility padrão port + adapter as integrações críticas seguem o padrão de porta com dois adapters — por exemplo, no financeiro convivem um adapter de demonstração (determinístico) e o adapter real do erp qual deles responde é configuração, não código as mesmas telas rodam com dado real ou com dado de demonstração conforme as variáveis de ambiente do tenant 15\ gestão de documentos e anexos a solução contempla anexos e documentos vinculados a cards, projetos e portfólios o armazenamento é feito no bucket minio exclusivo do tenant, resolvido dinamicamente pelo tenancit em ambientes sem minio configurado (por exemplo, execução local sem infraestrutura), o adapter `memory` atende a mesma interface, mantendo a semântica esperada — isso é intencional e serve ao ciclo de desenvolvimento e testes anexos e documentos são vinculados a cards, projetos e portfólios, com metadados de autoria e data o acesso a anexos respeita as capabilities do usuário no escopo do projeto o armazenamento físico é sempre no bucket do tenant chamador; não existe bucket compartilhado entre tenants adapters compatíveis minio (produção e hosted), minio hosted (topologia hosted), postgresql (fallback controlado) e memória (desenvolvimento e teste) 16\ auditoria e rastreabilidade a rastreabilidade é um requisito transversal do agility ela é atendida por dois mecanismos complementares trilha de histórico (`history`) — pacote de domínio próprio, append only, com snapshot renderizado por espécie de entidade registra quem mudou, quando e do que para o que; sobrevive ao hard delete; é uniforme entre agregados; não restaura versão anterior e não decide o que é campo relevante (o serviço da entidade é quem monta o snapshot) trilhas específicas de decisão — por exemplo, `ai estimate audit` guarda a sugestão do assistente de ia (adapter, provedor, modelo, confiança, prompt, resposta bruta, latência, tokens) e a decisão do usuário (aceito, editado, não usado), o que permite auditar o comportamento da ia a posteriori evento auditável descrição recomendada alteração de entidade de domínio registro em history actor interno, data/hora, resumo estruturado do que mudou alteração de membership ou papel preserva histórico (remoção mantém a linha inativa); dono do project não pode ser removido decisão sobre sugestão de ia registro em `ai estimate audit` com resposta bruta e escolha do usuário autenticação e resolução de tenant registro técnico com provedor e resultado; falha de resolução é fechada e auditada aplicação de migração registro em ledger próprio, com trava distribuída para evitar dupla aplicação integração externa registro do adapter chamado, resultado (sucesso/falha), correlação com a requisição de origem 17\ segurança da informação autenticação exclusiva por credencial reconhecida (oidc do keycloak, token da plataforma ou dev token quando habilitado); a api recusa subir sem um modo de autenticação declarado autorização por capability no escopo do tenant/projeto (view, comment, edit, approve, admin), avaliada antes de qualquer ação sensível menor privilégio explícito no client de diretório do keycloak (`view users`, `query users`), sem admin global falha fechada na resolução multi tenant — um erro na resolução rejeita a requisição em vez de servir dado de outro tenant isolamento físico por database e por bucket; nenhuma linha ou objeto compartilhada entre tenants credenciais e endpoints por ambiente vivem no plano de controle (tenancit) e não no código fonte nem em documentos públicos segredos de recursos (senha do banco, secret key do minio, token do gitlab, webhook secret) são mantidos fora de serialização json e de logs por design da estrutura de dados separação entre ambientes de desenvolvimento, homologação e produção, com topologias declaradas (`standalone rápido`, `hosted dev`, `local hosted`, `labdev`) e pipeline de ci/cd com estágios claros pipeline de ci/cd com gate obrigatório (workflow explícita os eventos válidos; runners kubernetes compartilhados não são privileged; hardening documentado no repositório) trilha de histórico transversal que sobrevive ao hard delete e serve como base de investigação em incidentes 18\ governança de dados e lgpd o agility manipula dados pessoais (identidade do usuário, e mail, participação em times e projetos), dados operacionais de projeto (cards, backlogs, dependências, riscos, objetivos) e, quando integrado ao erp corporativo, dados financeiros de projeto lidos do erp a arquitetura observa os princípios de necessidade, finalidade, controle de acesso e rastreabilidade tipo de dado exemplos controle recomendado dados pessoais nome, e mail e avatar do usuário; identidade interna estável distinta do subject do provedor acesso restrito por capability; identidade interna nunca expõe o subject do provedor de identidade em dto público dados de execução cards, boards, backlogs, sprints, pis, objetivos, riscos, dependências autorização por capability; histórico append only por entidade; hard delete preserva trilha dados de portfólio e investimento portfolio, value stream, portfolio epic, hipótese, mvp, investimento, wsjf escopo por workspace; separação entre epic de execução e portfolio epic dados financeiros orçamento consumido, disponibilidade de orçamento, posição de tesouraria, títulos leituras curadas contra o erp; sem edição a partir do agility; correção sempre no sistema de origem documentos anexos e documentos vinculados a cards, projetos e portfólios bucket exclusivo por tenant; capability herdada da entidade que ancora o anexo trilhas e histórico alterações de entidade, decisões sobre ia, migrações e integrações retenção append only; consulta autorizada; separação por tenant 19\ cenários de falha e continuidade cenário impacto comportamento esperado mitigação falha no keycloak do tenant usuários daquele tenant não conseguem autenticar ou renovar sessão bloquear acesso de forma segura e registrar indisponibilidade monitoramento do provedor; plano de contingência do idp; recuperação por tenant, sem afetar outros falha no tenancit resolução host → tenant e recursos falha falhar fechada (recusar a requisição) para evitar vazamento entre tenants monitoramento do plano de controle; recuperação do tenancit; readiness do agility exige o consumer alias falha no banco do tenant persistência e leitura do tenant afetadas retornar erro controlado; não migrar para banco compartilhado monitoramento por tenant; restauração isolada; trava/ledger de migração evitam corromper o schema falha no minio do tenant anexos e documentos do tenant indisponíveis registrar falha; bloquear operações dependentes verificação de bucket, permissões, disponibilidade e restauração; adapter memória disponível para desenvolvimento sem infraestrutura erro em migração instalação/atualização de schema fica incompleta em um tenant interromper a migração; ledger evita dupla aplicação executar por goose com trava distribuída; ledger de aplicação; script `migrate tenants` para percorrer todos falha em integração erp leituras financeiras contra o erp indisponíveis manter fluxo interno de projeto; expor status do adapter (demo vs erp) retentativas controladas; app key com escopo mínimo; diferenciação clara entre 401 (chave inválida) e 403 (operação fora da allow list ou identificador externo malformado) falha em integração gitlab integração de forge do tenant afetada registrar erro; não bloquear o restante do produto recurso opcional por tenant; token e webhook secret não vazam por serialização capability incorreta usuário perde acesso ou ganha acesso indevido a uma superfície aplicar menor privilégio; capability inexistente esconde a superfície sem apagar o dado revisão periódica de capabilities por projeto; revalidação no refresh (adr 0022) 20\ requisitos técnicos mínimos runtime go compatível com a versão declarada no `go mod` do repositório (série atual go 1 25) runtime bun compatível com a versão declarada no repositório para o build da spa (série atual bun 1 3) postgresql disponível por tenant, com permissão para o usuário aplicacional criar e evoluir objetos no schema `agility` minio (ou serviço s3 compatível) disponível por tenant, com bucket exclusivo por tenant e credencial de acesso dedicada keycloak disponível por tenant, com client de login próprio, audiência declarada e client de diretório com escopo mínimo plano de controle tenancit acessível pelo agility, com credencial de consumer e alias `agility ` publicados por tenant registro de contêineres corporativo acessível para publicação e para consumo pelo cluster de execução cluster kubernetes com ingress compatível com o path público único definido por instalação; helm chart aplicado pipeline de ci/cd (gitlab) com estágios de test, build e deploy; runners não privileged logs de auditoria e trilha de histórico habilitados e coletados pela observabilidade do cliente 21\ limitações conhecidas a criptografia aplicada a dado em repouso (banco e bucket) depende da política e da configuração de infraestrutura do cliente; o agility não impõe esquema criptográfico próprio sobre o armazenamento externo endpoints internos, portas, dsns e credenciais variam por ambiente e ficam fora deste documento por design a conformidade regulatória de cada cliente depende de evidências, políticas, contratos, auditorias e controles operacionais complementares aos previstos aqui a implantação depende da equipe de infraestrutura do cliente para disponibilização de keycloak, postgresql, minio, tenancit, ingress e credenciais por tenant recursos opcionais por tenant (gitlab forge, assistente de ia) só ficam ativos se o alias correspondente estiver publicado no tenancit daquele tenant a trilha de histórico registra quem mudou o quê, mas não restaura versão anterior por escrita — o snapshot é texto renderizado, projetado para comparação, não para reversão automática 22\ recomendações de implantação validar pré requisitos de infraestrutura antes do primeiro provisionamento de tenant publicar os recursos `agility postgres`, `agility minio` e `agility keycloak` no tenancit do tenant, com credenciais próprias por tenant executar as migrações pelo binário `migrate` com trava distribuída; para lote de tenants, usar `migrate tenants` configurar o client de login e o client de diretório do keycloak com o escopo mínimo previsto aplicar o helm chart com o path público único definido; confirmar que o gateway encaminha rotas de dados ao processo go e demais rotas à spa embarcada executar smoke test de autenticação, resolução multi tenant e acesso a `/healthz` e `/readyz` habilitar recursos opcionais (`agility gitlab`, `agility ai`) apenas quando o cliente pedir, com contrato claro sobre adapter e escopo configurar coleta dos logs de auditoria e da trilha de histórico na observabilidade do cliente formalizar aceite técnico, funcional e de segurança antes da entrada em produção do primeiro tenant 23\ checklist de validação pergunta atendido? observação a arquitetura foi descrita sem exposição de credenciais, endpoints privados ou identificadores operacionais? sim documento adaptado para uso externo controlado os componentes principais foram listados? sim spa, api, tenancit, keycloak, postgresql, minio, adapters, ia e trilha de histórico descritos o fluxo lógico da aplicação foi descrito? sim da chegada da requisição no path público único até a persistência no banco/bucket do tenant o modelo de autenticação e autorização foi explicado? sim três origens de credencial reduzidas ao mesmo principal; capabilities canônicas descritas a camada de dados foi documentada? sim um database por tenant, schema fixo, migrações versionadas com trava e ledger próprios o modelo multi tenant foi documentado? sim resolução host → tenant pelo tenancit; recursos por alias; falha fechada as integrações externas foram mapeadas? sim keycloak, minio, gitlab (opcional), ia (opcional) e erp corporativo (leitura curada) as limitações foram informadas? sim incluídas de forma transparente, com atenção à parte governada pela infraestrutura do cliente há recomendações práticas de implantação? sim checklist de implantação incluído 25\ glossário termo definição workspace raiz organizacional visível; único destino global navegável; contém projects, teams, arts, portfolios, membros e configurações tenant contexto técnico que resolve recursos e um database isolado por host; não é entidade exposta e não substitui autorização de workspace project contexto canônico de entrega, com owner, nível de acesso, eixos de forma de trabalho, team, board e capabilities team grupo durável de pessoas do workspace que participa de projects membership associação explícita e preservadora de histórico; a remoção mantém a linha inativa; o owner do project não pode ser removido capability de autorização permissão do principal view, comment, edit, approve, admin capability de project item da lista derivada pelo servidor que habilita superfícies como board, backlog, wbs, gantt e finance board / quadro visão operacional do trabalho de um project/team, com etapas e cards lane / etapa coluna do board com título livre, ordem e status comportamental (not started, in progress, done) task / card item de execução em uma etapa, com responsável, datas, estimativa, anexos, horas, custos e histórico sprint cadência de um time scrum em um project (planning, active, completed, cancelled) art agile release train do workspace; coordena times, pis, backlog, capacidade, prontidão, riscos e inspect & adapt pi planning interval do art, com iterações, objetivos, capacidade e prontidão portfolio contexto de investimento do workspace, com orçamento lean e value streams portfolio epic hipótese de investimento com hipótese, mvp, investimento e wsjf; distinto do epic de execução tenancit plano de controle multi tenant que resolve host → tenant e devolve recursos por alias `agility ` keycloak provedor de identidade utilizado para autenticação, tokens, perfis, roles e permissões, configurado por tenant audit log / history registro append only de eventos técnicos e funcionais usado para rastreabilidade e conformidade