ARB - Comitê de Arquitetura Plugin

Plugin frontend para Backstage que fornece interface de gerenciamento para projetos do Comitê de Arquitetura (ARB).

Funcionalidades

• ✅ Listar todos os projetos apresentados e pendentes de apresentação no ARB
• ✅ Criar novos projetos para apresentação
• ✅ Atualizar projetos existentes
• ✅ Deletar projetos
• ✅ Visualizar histórico de auditoria completo de cada projeto
• ✅ Interface intuitiva com Material-UI

Estrutura de Dados

Cada projeto ARB possui os seguintes campos:

• Nome do projeto
• Responsável - Nome do responsável pelo projeto
• Status - Aprovado, Reprovado, Pendente, Aprovado c/ ressalvas
• Motivo - Justificativa da decisão
• Observações - Comentários adicionais
• Data de apresentação
• Link da documentação
• Link da gravação do ARB
• Número do chamado
• Aprovações - Arquitetura, Infra, Segurança, FinOps, Identidades, Monitoria
• Auditoria - Histórico completo de alterações com usuário, data/hora e detalhes
• Data de criação - Timestamp de criação do projeto
• Última modificação - Timestamp da última atualização

Arquitetura

Este plugin frontend consome uma API REST backend que gerencia o armazenamento e a lógica de negócio dos projetos ARB. O backend pode utilizar diferentes storages (Azure Repos, banco de dados, etc.) sem impactar o frontend.

Benefícios da Arquitetura

• 🔒 Segurança - Credenciais e tokens ficam apenas no backend
• 🔄 Separação de responsabilidades - Frontend focado em UI/UX
• 🔌 Flexibilidade - Backend pode trocar de storage sem afetar o frontend
• 📝 Auditoria centralizada - Todas as operações passam pelo backend
• 🚀 Autenticação automática - Gerenciada pelo Backstage

Instalação

Pré-requisitos

• Backstage instalado (standalone ou via Helm Chart)
• Backend ARB rodando e acessível (veja backstage-plugin-arb-backend)

Configuração

1. Instale as dependências:

cd backstage-plugin-arb-frontend
yarn install

2. Configure o app-config.yaml:

backend:
  baseUrl: http://localhost:7007

arb:
  backend:
    baseUrl: ${backend.baseUrl}/api/arb/v1

3. Build do plugin:

yarn build

Plugin Dinâmico

Para usar como plugin dinâmico no Red Hat Developer Hub ou Backstage com suporte a dynamic plugins:

1. Exporte o plugin:

yarn export-dynamic

2. Configure o dynamic-plugins.yaml:

dynamicPlugins:
  frontend:
    veecode-platform.plugin-arb-dynamic:
      dynamicRoutes:
        - path: /arb
          importName: ArbPage
          menuItem:
            text: ARB
            icon: Architecture
      appIcons:
        - name: arbIcon
          importName: ArbIcon

3. Configure o item de menu na sidebar:

app:
  sidebar:
    items:
      - id: arb-navigation-item
        title: ARB
        to: /arb
        icon: Architecture

Desenvolvimento

Modo de Desenvolvimento Local

1. Certifique-se de que o backend está rodando:

# Em outro terminal, inicie o backend
cd backstage-plugin-arb-backend
yarn start

2. Inicie o frontend em modo dev:

cd backstage-plugin-arb-frontend
yarn start

O plugin estará disponível em http://localhost:3000/arb

Estrutura do Projeto

backstage-plugin-arb-frontend/
├── src/
│   ├── api/
│   │   ├── ArbBackendClient.ts  # Client que consome a API backend
│   │   └── index.ts              # Tipos e API ref
│   ├── components/
│   │   ├── ArbPage.tsx           # Página principal
│   │   ├── ArbProjectsTable.tsx  # Tabela de projetos
│   │   └── ArbNavigationItem.tsx # Item do menu
│   ├── plugin.ts                 # Configuração do plugin
│   └── index.ts                  # Exports públicos
├── dev/
│   └── index.tsx                 # Ambiente de dev standalone
└── package.json

API Backend

O plugin consome os seguintes endpoints do backend:

Endpoints Disponíveis

• GET /api/arb/v1/health - Health check do backend
• GET /api/arb/v1/arb - Listar todos os projetos
• GET /api/arb/v1/arb/:id - Buscar um projeto específico por ID
• POST /api/arb/v1/arb - Criar um novo projeto
• PUT /api/arb/v1/arb/:id - Atualizar um projeto existente
• DELETE /api/arb/v1/arb/:id - Deletar um projeto

Modelo de Dados

interface ArbProject {
  id: string;
  nome: string;
  responsavel: string;
  status: string;
  motivo: string;
  observacoes: string;
  dataApresentacao: string;
  linkDocumentacao: string;
  linkGravacao: string;
  numeroChamado: string;
  aprovacoes: {
    arquitetura: boolean;
    infra: boolean;
    seguranca: boolean;
    finops: boolean;
    identidades: boolean;
    monitoria: boolean;
  };
  auditoria: AuditLog[];
  dataCriacao: string;
  ultimaModificacao: string;
}

Como Funciona

Discovery API

O plugin utiliza o DiscoveryApi do Backstage para descobrir dinamicamente a URL do backend:

const baseUrl = await this.discoveryApi.getBaseUrl('arb');
// Retorna: http://localhost:7007/api/arb/v1

Autenticação

O FetchApi do Backstage gerencia automaticamente a autenticação entre frontend e backend. Não é necessário configurar tokens ou credenciais no frontend.

Exemplo de Uso no Código

import { useApi } from '@backstage/core-plugin-api';
import { arbApiRef } from '../api';

// No componente
const arbApi = useApi(arbApiRef);

// Listar projetos
const projects = await arbApi.getProjects();

// Criar projeto
const newProject = await arbApi.createProject(projectData, usuario);

// Atualizar projeto
await arbApi.updateProject(id, updates, usuario);

// Deletar projeto
await arbApi.deleteProject(id, usuario);

Troubleshooting

Erro: "Cannot connect to backend"

Verifique se:

1. O backend está rodando em http://localhost:7007
2. A configuração no app-config.yaml está correta
3. O endpoint /api/arb/v1/arb está acessível

Erro: "Discovery failed"

Certifique-se de que:

1. O plugin backend está registrado com o ID 'arb'
2. O backend está rodando e acessível
3. O app-config.yaml contém a configuração correta

Projetos não aparecem na tabela

Verifique:

1. Se há projetos cadastrados no backend
2. Os logs do console do browser para erros
3. A resposta da API usando DevTools (Network tab)

Licença

Apache-2.0