core/README.md

# 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](#-visão-geral)
- [Pré-requisitos](#-pré-requisitos)
- [Instalação Rápida](#-instalação-rápida)
- [Configuração Detalhada](#-configuração-detalhada)
  - [Variáveis de Ambiente](#variáveis-de-ambiente)
  - [Setup Appwrite Cloud](#setup-appwrite-cloud)
- [Executando o Projeto](#-executando-o-projeto)
- [Estrutura do Projeto](#-estrutura-do-projeto)
- [Scripts Disponíveis](#-scripts-disponíveis)
- [Verificação e Testes](#-verificação-e-testes)
- [Troubleshooting](#-troubleshooting)
- [Deploy](#-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)

```bash
# 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](https://nodejs.org) |
| **npm** | 9.x ou superior | `npm --version` | Vem com Node.js |
| **Deno** | 1.40+ | `deno --version` | [deno.land](https://deno.land/manual/getting_started/installation) |
| **Git** | 2.x | `git --version` | [git-scm.com](https://git-scm.com) |

### Conta Appwrite Cloud

Você também precisa de uma conta no **[Appwrite Cloud](https://cloud.appwrite.io)** (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

```bash
# 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:

```bash
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](https://appwrite.io/docs/command-line)
2. Execute:
   ```bash
   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
  - Gere um **API Token** no Cloudflare com permissões **Zone:Read** e **Workers:Read**.
  - Salve o token no Appwrite na coleção `cloud_accounts` com `provider=cloudflare`, `apiKey` e, opcionalmente, `cloudflareAccountId` (usado para listar Workers).

## 🏃 Executando o Projeto

### Desenvolvimento

#### Executar Tudo Junto

```bash
npm run dev:web
```

Isso inicia:
- **Landing** em http://localhost:8000
- **Dashboard** em http://localhost:5173

#### Executar Componentes Separadamente

**Landing (Fresh + Deno):**
```bash
npm run dev:landing
# Ou: cd landing && deno task start
```
Acesse: http://localhost:8000

**Dashboard (React + Vite):**
```bash
npm run dev:dashboard
# Ou: cd dashboard && npm run dev
```
Acesse: http://localhost:5173

**Backend (Node.js + TypeScript):**
```bash
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:**
```bash
cd dashboard
npm run build
```
Saída em `dashboard/dist/`

**Landing:**
```bash
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:

```bash
# 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:**
```bash
cd dashboard
npm install
```

### Erro: "deno: command not found"

**Solução:**
```bash
# 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:**
```javascript
// 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:**
```bash
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:**
```bash
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](https://vercel.com) (zero config)
- [Netlify](https://netlify.com)
- [Cloudflare Pages](https://pages.cloudflare.com)

```bash
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](https://deno.com/deploy) (nativo Fresh)
- [Fly.io](https://fly.io)

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

### Appwrite Functions

Via Appwrite CLI:
```bash
appwrite deploy function
```

Ou manualmente via Appwrite Console → Functions.

## 📚 Recursos Adicionais

- [Documentação Appwrite](https://appwrite.io/docs)
- [Documentação Fresh](https://fresh.deno.dev/docs)
- [Documentação Vite](https://vitejs.dev)
- [Documentação React](https://react.dev)
- [Deno Manual](https://deno.land/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](LICENSE) (ou especifique sua licença).

---

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