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 três 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: Appwrite Cloud - BaaS (Backend as a Service) com:

• 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

🛠 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 dashboard
cd dashboard
npm install
cd ..

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

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

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

# 7. Execute o projeto
npm run dev:web

⚙️ Configuração Detalhada

Variáveis de Ambiente

O arquivo .env na raiz do projeto contém todas as configurações necessárias. Copie o .env.example e preencha os valores:

cp .env.example .env

Referência Completa de Variáveis

Variável	Onde Obter	Obrigatória	Descrição
Configuração Server-Side (Scripts Node.js e Functions)
APPWRITE_ENDPOINT	Fixo	✅	URL da API Appwrite. Use https://cloud.appwrite.io/v1
APPWRITE_PROJECT_ID	Console Appwrite	✅	ID do projeto. Obtido em: Dashboard → Seu Projeto → Settings
APPWRITE_API_KEY	Console Appwrite	✅	Chave API com permissões Admin. Criar em: Settings → API Keys → Create API Key → Selecione todos os scopes
APPWRITE_FUNCTIONS_ENDPOINT	Opcional	❌	Endpoint customizado para Functions. Deixe vazio para usar o mesmo do APPWRITE_ENDPOINT
APPWRITE_FUNCTIONS_API_KEY	Opcional	❌	API Key separada para Functions. Deixe vazio para usar APPWRITE_API_KEY
Configuração Client-Side (React Dashboard - Vite)
VITE_APPWRITE_ENDPOINT	Fixo	✅	Mesmo que APPWRITE_ENDPOINT. Prefixo VITE_ expõe no browser
VITE_APPWRITE_PROJECT_ID	Console Appwrite	✅	Mesmo que APPWRITE_PROJECT_ID
VITE_APPWRITE_DATABASE_ID	Console Appwrite	✅	ID do Database criado. Obtido em: Databases → Seu Database → Settings
VITE_APPWRITE_COLLECTION_SERVERS_ID	Console Appwrite	✅	ID da coleção servers. Obtido em: Databases → Collections → servers → Settings
VITE_APPWRITE_COLLECTION_GITHUB_REPOS_ID	Console Appwrite	✅	ID da coleção github_repos
VITE_APPWRITE_COLLECTION_AUDIT_LOGS_ID	Console Appwrite	✅	ID da coleção audit_logs (usado para Realtime no terminal)
VITE_APPWRITE_COLLECTION_CLOUDFLARE_ACCOUNTS_ID	Console Appwrite	✅	ID da coleção cloud_accounts ou cloudflare_accounts

⚠️ IMPORTANTE: Variáveis com prefixo VITE_ são expostas no JavaScript do browser. NUNCA coloque informações sensíveis (API Keys) nelas!

Setup Appwrite Cloud

Siga este passo a passo para configurar o backend:

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

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/
├── .env                     # Variáveis de ambiente (NÃO commitar!)
├── .env.example             # Template de variáveis
├── package.json             # Scripts raiz e npm-run-all
├── README.md                # 📄 Este arquivo
├── SECURITY.md              # Política de segurança
├── appwrite.json            # Configuração Appwrite CLI
├── appwrite-databases-schema.md  # Schema detalhado do banco
│
├── 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: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

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 ../.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 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