Core Platform Monorepo

Plataforma DevOps completa com Landing Page (Fresh + Deno), Dashboard (React + Vite) e Backend Appwrite Cloud. Sistema integrado com autenticação, banco de dados em tempo real, e funções serverless para gerenciamento de servidores, repositórios GitHub e contas Cloudflare.

📋 Índice

• Visão Geral
• Pré-requisitos
• Instalação Rápida
• Configuração Detalhada
  • Variáveis de Ambiente
  • Setup Appwrite Cloud
• Executando o Projeto
• Estrutura do Projeto
• Scripts Disponíveis
• Verificação e Testes
• Troubleshooting
• Deploy

🎯 Visão Geral

Este monorepo contém quatro componentes principais:

• Landing Page: Interface pública desenvolvida com Fresh (framework Deno) e Tailwind CSS
• Dashboard: Painel administrativo em React + TypeScript + Vite com integração Appwrite
• Appwrite Functions: Três funções serverless (hello-world, sync-github, check-cloudflare-status)
• Backend (Node.js + TypeScript): API administrativa multi-tenant para gerenciar projetos Appwrite

Infra principal Appwrite (por projeto):

• Autenticação (Email/Password)
• Database com 4 coleções (servers, github_repos, audit_logs, cloud_accounts)
• Realtime subscriptions para logs ao vivo
• Functions para automação

🧱 Arquitetura do Backend Multi-tenant

• Tenants representam empresas/clientes.
• Cada tenant possui um ou mais projetos Appwrite com endpoint + API key próprios.
• O backend persiste o controle local em backend/data/tenants.json.
• Autenticação administrativa via ADMIN_API_TOKEN.

🔁 Fluxo multi-tenant (resumo)

1. POST /tenants cria o tenant.
2. POST /tenants/:id/appwrite-project registra o projeto Appwrite do tenant.
3. POST /appwrite/setup aplica schema base automaticamente.
4. GET /tenants/:id/appwrite-projects lista projetos vinculados.

Como adicionar um novo Appwrite (exemplo rápido)

# 1) Criar tenant
curl -X POST http://localhost:4000/tenants \\
  -H \"Authorization: Bearer <ADMIN_API_TOKEN>\" \\
  -H \"Content-Type: application/json\" \\
  -d '{\"name\":\"Acme Corp\"}'

# 2) Registrar projeto Appwrite do tenant
curl -X POST http://localhost:4000/tenants/<TENANT_ID>/appwrite-project \\
  -H \"Authorization: Bearer <ADMIN_API_TOKEN>\" \\
  -H \"Content-Type: application/json\" \\
  -d '{\"name\":\"Acme Project\",\"endpoint\":\"https://cloud.appwrite.io/v1\",\"projectId\":\"<PROJECT_ID>\",\"apiKey\":\"<API_KEY>\"}'

# 3) Aplicar schema base
curl -X POST http://localhost:4000/appwrite/setup \\
  -H \"Authorization: Bearer <ADMIN_API_TOKEN>\" \\
  -H \"Content-Type: application/json\" \\
  -d '{\"tenantId\":\"<TENANT_ID>\",\"projectRef\":\"<PROJECT_ID>\"}'

🛠 Pré-requisitos

Certifique-se de ter instalado:

Software	Versão Mínima	Como Verificar	Download
Node.js	18.x ou superior	node --version	nodejs.org
npm	9.x ou superior	npm --version	Vem com Node.js
Deno	1.40+	deno --version	deno.land
Git	2.x	git --version	git-scm.com

Conta Appwrite Cloud

Você também precisa de uma conta no Appwrite Cloud (gratuito):

1. Acesse https://cloud.appwrite.io e crie uma conta
2. Crie um novo projeto
3. Anote o Project ID que será usado nas variáveis de ambiente

🚀 Instalação Rápida

# 1. Clone o repositório
git clone <repository-url>
cd core

# 2. Instale as dependências raiz
npm install

# 3. Instale as dependências do backend
cd backend
npm install
cd ..

# 4. Instale as dependências do dashboard
cd dashboard
npm install
cd ..

# 5. Verifique se o Deno está instalado
deno --version
# Se não estiver, instale: curl -fsSL https://deno.land/install.sh | sh

# 6. Configure as variáveis de ambiente
cp backend/.env.example backend/.env
# Edite o backend/.env com suas credenciais Appwrite (veja seção abaixo)

# 7. Configure o Appwrite Cloud (veja seção "Setup Appwrite Cloud")

# 8. Execute o projeto
npm run dev:web
npm run dev:backend

⚙️ Configuração Detalhada

Variáveis de Ambiente

O backend usa um arquivo .env próprio em backend/.env. Copie o .env.example do backend e preencha os valores:

cp backend/.env.example backend/.env

Referência Completa de Variáveis (Backend)

Variável	Obrigatória	Descrição
ADMIN_API_TOKEN	✅	Token de acesso administrativo (Authorization: Bearer ...)
APPWRITE_ADMIN_ENDPOINT	✅	Endpoint Appwrite para criar projetos
APPWRITE_ADMIN_PROJECT_ID	✅	Project ID administrativo (normalmente console)
APPWRITE_ADMIN_API_KEY	✅	API Key com permissões admin para projetos
DEFAULT_APPWRITE_ENDPOINT	✅	Endpoint padrão para novos tenants
APPWRITE_DEFAULT_RUNTIME	❌	Runtime padrão das Functions (ex: deno-1.35)
DATA_DIR	❌	Diretório local para persistir tenants (default: ./data)

As variáveis client-side do Dashboard permanecem em seu próprio .env (prefixo VITE_). Nunca use API keys no front-end.

Setup Appwrite Cloud

Siga este passo a passo para configurar o Appwrite usado pelo dashboard. O backend multi-tenant aplica o próprio schema via POST /appwrite/setup quando necessário.

1. Criar Projeto

1. Acesse https://cloud.appwrite.io
2. Clique em Create Project
3. Dê um nome (ex: "DevOps Platform")
4. Copie o Project ID e salve no .env:

   APPWRITE_PROJECT_ID=seu_project_id_aqui
   VITE_APPWRITE_PROJECT_ID=seu_project_id_aqui
   

2. Criar API Key

1. No menu lateral, vá em Settings → API Keys
2. Clique em Create API Key
3. Nome: "Admin Key" ou "Server Key"
4. Scopes: Marque todos (necessário para operações administrativas)
5. Copie a API Key (só aparece uma vez!) e salve no .env:

   APPWRITE_API_KEY=sua_api_key_aqui
   

3. Criar Database

1. No menu lateral, clique em Databases
2. Clique em Create Database
3. Nome: DevOpsPlatform (ou outro de sua escolha)
4. Copie o Database ID e salve no .env:

   VITE_APPWRITE_DATABASE_ID=seu_database_id_aqui
   

4. Criar Collections

Dentro do Database criado, crie as 4 coleções com os seguintes schemas:

Collection 1: servers

Campo	Tipo	Required	Array	Default
name	String	Sim	Não	-
ip	String	Sim	Não	-
status	Enum	Sim	Não	online
region	String	Não	Não	-

Enum status: online, offline

ID sugerido: servers

Após criar, copie o ID:

VITE_APPWRITE_COLLECTION_SERVERS_ID=servers

Collection 2: github_repos

Campo	Tipo	Required	Array	Default
repo_name	String	Sim	Não	-
url	URL	Sim	Não	-
last_commit	String	Não	Não	-
status	String	Não	Não	active

ID sugerido: github_repos

VITE_APPWRITE_COLLECTION_GITHUB_REPOS_ID=github_repos

Collection 3: audit_logs

Campo	Tipo	Required	Array	Default
event	String	Sim	Não	-
user_id	String	Sim	Não	-
timestamp	DateTime	Sim	Não	-

ID sugerido: audit_logs

⚠️ Esta coleção é usada pelo Realtime Subscription no terminal do dashboard!

VITE_APPWRITE_COLLECTION_AUDIT_LOGS_ID=audit_logs

Collection 4: cloud_accounts

Campo	Tipo	Required	Array	Default
provider	String	Sim	Não	-
apiKey	String	Sim	Não	-
label	String	Não	Não	-

ID sugerido: cloud_accounts

VITE_APPWRITE_COLLECTION_CLOUDFLARE_ACCOUNTS_ID=cloud_accounts

5. Configurar Autenticação

1. No menu lateral, clique em Auth
2. Vá em Settings
3. Ative o provedor Email/Password
4. (Opcional) Configure limites de taxa e outras opções de segurança

6. Criar Usuário de Teste

1. Em Auth → Users
2. Clique em Create User
3. Preencha:
   • Email: admin@test.com
   • Password: admin123 (altere para algo seguro!)
   • Name: Admin User
4. Clique em Create

7. Implantar Functions (Opcional)

As funções estão em appwrite-functions/. Para implantá-las:

1. Instale a Appwrite CLI
2. Execute:

   appwrite login
   appwrite deploy function
   

3. Ou crie manualmente via Console:
   • Functions → Create Function
   • Faça upload do código de cada pasta em appwrite-functions/

Funções disponíveis:

• hello-world: Função exemplo
• sync-github: Sincroniza dados de repositórios GitHub
• check-cloudflare-status: Verifica status de contas Cloudflare

🏃 Executando o Projeto

Desenvolvimento

Executar Tudo Junto

npm run dev:web

Isso inicia:

• Landing em http://localhost:8000
• Dashboard em http://localhost:5173

Executar Componentes Separadamente

Landing (Fresh + Deno):

npm run dev:landing
# Ou: cd landing && deno task start

Acesse: http://localhost:8000

Dashboard (React + Vite):

npm run dev:dashboard
# Ou: cd dashboard && npm run dev

Acesse: http://localhost:5173

Backend (Node.js + TypeScript):

npm run dev:backend
# Ou: cd backend && npm run dev

Acesse: http://localhost:4000

Login no dashboard usa as credenciais criadas no Appwrite (ex: admin@test.com / admin123).

Build para Produção

Dashboard:

cd dashboard
npm run build

Saída em dashboard/dist/

Landing:

cd landing
deno task build

📁 Estrutura do Projeto

core/
├── package.json             # Scripts raiz e npm-run-all
├── README.md                # 📄 Este arquivo
├── backend/                 # 🧠 API administrativa (Node + TS)
│   ├── src/
│   │   ├── modules/          # Tenants, projects, auth, finops
│   │   ├── lib/              # Appwrite SDK, env, logger
│   │   ├── scripts/          # Setup Appwrite
│   │   ├── config/           # appwrite.json
│   │   ├── docs/             # Docs backend
│   │   └── main.ts           # Entry point
│   ├── Dockerfile
│   ├── docker-compose.yml
│   ├── package.json
│   ├── tsconfig.json
│   └── .env.example
│
├── dashboard/               # 🎨 Painel React + Vite
│   ├── src/
│   │   ├── components/      # Componentes reutilizáveis
│   │   ├── pages/           # Páginas/rotas
│   │   ├── lib/             # SDK Appwrite, utilitários
│   │   ├── App.tsx          # Componente raiz
│   │   └── main.tsx         # Entry point
│   ├── package.json         # Dependências do dashboard
│   ├── vite.config.ts       # Configuração Vite
│   ├── tailwind.config.js   # Configuração Tailwind
│   └── README.md            # Documentação específica
│
├── landing/                 # 🚀 Landing Page (Fresh + Deno)
│   ├── routes/              # Rotas Fresh
│   ├── islands/             # Componentes interativos (ilhas)
│   ├── components/          # Componentes estáticos
│   ├── static/              # Arquivos estáticos
│   ├── deno.json            # Configuração e tarefas Deno
│   ├── fresh.config.ts      # Configuração Fresh
│   ├── main.ts              # Entry point
│   └── README.md            # Documentação específica
│
└── appwrite-functions/      # ⚡ Funções Serverless
    ├── hello-world/
    ├── sync-github/
    └── check-cloudflare-status/

📜 Scripts Disponíveis

Raiz

Script	Comando	Descrição
dev:backend	npm run dev:backend	Inicia a API backend multi-tenant
dev:dashboard	npm run dev:dashboard	Inicia somente o dashboard
dev:landing	npm run dev:landing	Inicia somente a landing
dev:web	npm run dev:web	Inicia dashboard + landing em paralelo
lint:dashboard	npm run lint:dashboard	Executa ESLint no dashboard
setup:appwrite	npm run setup:appwrite	Aplica o schema base Appwrite

Dashboard (cd dashboard)

Script	Comando	Descrição
dev	npm run dev	Inicia dev server Vite (porta 5173)
build	npm run build	Compila TypeScript + build otimizado
preview	npm run preview	Testa build de produção localmente
lint	npm run lint	Verifica código com ESLint

Landing (cd landing)

Script	Comando	Descrição
start	deno task start	Inicia dev server Fresh (porta 8000)
build	deno task build	Gera build de produção
preview	deno task preview	Serve build de produção
check	deno task check	Formata, lint e type-check

✅ Verificação e Testes

Checklist de Instalação

Execute estes comandos para verificar se tudo está configurado corretamente:

# 1. Verificar versões
node --version   # Deve ser >= 18
npm --version    # Deve ser >= 9
deno --version   # Deve ser >= 1.40

# 2. Verificar instalação de dependências
npm ls npm-run-all           # Raiz
cd dashboard && npm ls appwrite  # Dashboard
cd ../landing && deno info      # Landing

# 3. Testar build do dashboard
cd dashboard
npm run build
# Deve gerar pasta dist/ sem erros

# 4. Testar lint
npm run lint
# Deve passar sem erros (warnings ok)

# 5. Testar landing page
cd ../landing
deno task check
# Deve passar formatting, linting e type-check

# 6. Verificar arquivo .env
cat backend/.env
# Deve ter todos os IDs preenchidos (não vazios)

Testes Manuais

1. Dashboard (http://localhost:5173):

   • Login deve funcionar com usuário criado no Appwrite
   • Overview deve mostrar widgets de servidores, repos e logs
   • Terminal inferior deve conectar ao Realtime (audit_logs)

2. Landing (http://localhost:8000):

   • Página deve carregar sem erros
   • Navegação deve funcionar
   • Componentes interativos (Counter, ServerStatus) devem responder

🔧 Troubleshooting

Erro: "Cannot find module 'appwrite'"

Solução:

cd dashboard
npm install

Erro: "deno: command not found"

Solução:

# Linux/Mac
curl -fsSL https://deno.land/install.sh | sh

# Windows (PowerShell)
irm https://deno.land/install.ps1 | iex

# Adicione ao PATH (Linux/Mac):
echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Dashboard não conecta ao Appwrite

Checklist:

1. Arquivo .env existe e tem variáveis VITE_* preenchidas?
2. Project ID está correto?
3. Database existe no Appwrite Cloud?
4. Collections foram criadas com os IDs corretos?
5. Usuário de autenticação foi criado?

Debug:

// No console do browser (F12)
console.log(import.meta.env.VITE_APPWRITE_PROJECT_ID)
// Deve mostrar seu Project ID, não "undefined"

Erro: "Failed to fetch" no dashboard

Possível causa: CORS ou endpoint incorreto.

Solução:

1. Verifique se VITE_APPWRITE_ENDPOINT está correto: https://cloud.appwrite.io/v1
2. No Appwrite Console → Settings → Platforms, adicione:
   • Web Platform com hostname localhost

Landing page não carrega dependências

Solução:

cd landing
# Limpar cache do Deno
deno cache --reload dev.ts
# Tentar novamente
deno task start

Build do dashboard falha

Erro comum: TypeScript errors

Solução:

cd dashboard
# Verificar erros de tipo
npx tsc --noEmit
# Se muitos erros, verifique versões:
npm ls typescript
npm ls @types/react

🚀 Deploy

Dashboard (Vite App)

Opções recomendadas:

• Vercel (zero config)
• Netlify
• Cloudflare Pages

cd dashboard
npm run build
# Upload da pasta dist/ para seu provider

Importante: Configure as variáveis VITE_* no painel do provider!

Landing (Deno Fresh)

Opções recomendadas:

• Deno Deploy (nativo Fresh)
• Fly.io

cd landing
deno task build
# Ou deploy direto para Deno Deploy

Appwrite Functions

Via Appwrite CLI:

appwrite deploy function

Ou manualmente via Appwrite Console → Functions.

📚 Recursos Adicionais

• Documentação Appwrite
• Documentação Fresh
• Documentação Vite
• Documentação React
• Deno Manual

🔐 Segurança

• NUNCA commite o arquivo .env
• API Keys devem ter scopes mínimos necessários em produção
• Habilite MFA no Appwrite Console
• Revise backend/src/docs/SECURITY.md para reportar vulnerabilidades

📝 Licença

Este projeto está sob a licença MIT (ou especifique sua licença).

---

Desenvolvido com ❤️ usando Appwrite Cloud, Fresh, React e Deno