# OutAgent - Visão Geral do Sistema

## O que é

**OutAgent** é uma aplicação web de produtividade pessoal com foco em gestão de tarefas, metas diárias, acompanhamento de streaks (sequências) e timer Pomodoro. Funciona como um assistente pessoal digital.

## Tech Stack

| Camada | Tecnologia |
|---|---|
| **Frontend** | React 19 + Vite 7 |
| **UI** | CSS customizado (sem framework), React Icons |
| **Backend** | Node.js + Express 5 |
| **Banco de Dados** | MySQL (via mysql2) |
| **Autenticação** | JWT (jsonwebtoken) + bcryptjs |
| **Utilidades** | date-fns, uuid, dotenv, cors |

## Estrutura de Arquivos

```
outAgent/
├── client/                     # Frontend React
│   ├── src/
│   │   ├── App.jsx             # Roteamento principal
│   │   ├── components/         # Sidebar, TaskItem, PomodoroFeedbackModal
│   │   ├── contexts/           # ToastContext, PomodoroContext
│   │   ├── hooks/              # useData (data fetching)
│   │   ├── pages/              # Dashboard, Tasks, Goals, Streaks,
│   │   │                       # History, Integrations, Settings, Admin, Auth
│   │   └── services/
│   │       └── api.js          # Cliente de API
│   └── index.css               # Estilos globais
├── server/
│   ├── index.js                # Entry point Express
│   ├── middleware/
│   │   └── auth.js             # JWT auth + admin impersonation
│   ├── routes/
│   │   ├── auth.js             # Login / Register
│   │   ├── tasks.js            # CRUD tarefas
│   │   ├── goals.js            # Metas diárias
│   │   ├── streaks.js          # Streaks / sequências
│   │   ├── pomodoro.js         # Sessões Pomodoro
│   │   ├── activity.js         # Log de atividade
│   │   ├── dashboard.js        # Dados do dashboard
│   │   └── integrations/
│   │       └── github.js       # Integração GitHub
│   ├── services/
│   │   └── githubService.js    # Lógica de integração GitHub
│   └── database/
│       ├── init.js             # Inicialização MySQL
│       └── schema.sql          # Definição de tabelas
└── DEPLOYMENT.md, CPANEL_DEPLOY.md  # Docs de deploy
```

## Páginas do Frontend

| Página | Descrição |
|---|---|
| **Auth** | Login e registro |
| **Dashboard** | Visão geral com métricas, atividades recentes |
| **Tasks** | CRUD de tarefas com drag & drop, filtros, categorias, prioridades |
| **Goals** | Metas diárias com tracking de progresso |
| **Streaks** | Acompanhamento de sequências de produtividade |
| **History** | Histórico de atividades passadas |
| **Integrations** | Conexão com GitHub e outros serviços |
| **Settings** | Configurações da conta |
| **Admin** | Gestão de usuários (role-based, com impersonation) |

## Banco de Dados - Tabelas

| Tabela | Descrição |
|---|---|
| `users` | Usuários com nome, email, senha (hashed), role (user/admin), timezone, preferences (JSON) |
| `tasks` | Tarefas com título, descrição, categoria, prioridade, status, data/hora de vencimento, recorrência, tags, posição (drag & drop) |
| `daily_goals` | Metas diárias com target, valor atual, unidade, status |
| `streaks` | Sequências de hábito com ícone, streak atual, melhor streak |
| `categories` | Categorias estáticas com cor e ícone |
| `integrations` | Integrações externas (provider, config JSON, sync) |
| `activity_log` | Log de ações do usuário (audit trail) |
| `pomodoro_sessions` | Sessões Pomodoro (tipo, duração, produtividade, feedback) |

### Relacionamentos

Todos os dados (`tasks`, `daily_goals`, `streaks`, `integrations`, `activity_log`, `pomodoro_sessions`) têm `user_id` como foreign key para `users`, com `ON DELETE CASCADE`. Sesões Pomodoro também referenciam `tasks` com `ON DELETE SET NULL`.

## Autenticação

- **JWT** com tokens válidos por 7 dias
- **Senhas** hasheadas com bcrypt
- **Admin impersonation**: admins podem visualizar dados de outros usuários via header `x-view-asuser`
- **Middleware `authOptional`**: endpoints que aceitam dados de usuário se houver token, mas não bloqueiam acesso

## Rotas da API

### Públicas
| Método | Rota | Descrição |
|---|---|---|
| POST | `/api/auth/register` | Registro de novo usuário |
| POST | `/api/auth/login` | Login |
| GET | `/api/health` | Health check |

### Protegidas (requer autenticação)
| Método | Rota | Descrição |
|---|---|---|
| CRUD | `/api/tasks` | Gerenciamento de tarefas |
| CRUD | `/api/goals` | Metas diárias |
| CRUD | `/api/streaks` | Streaks |
| GET | `/api/dashboard` | Dados do dashboard consolidado |
| CRUD | `/api/pomodoro` | Sessões Pomodoro |
| GET | `/api/activity` | Log de atividades |
| -- | `/api/integrations/github` | Integração GitHub (OAuth + sync) |

## Features Notáveis

- **Categorias de tarefas**: trabalho, pessoal, saúde, estudo, finanças, outro
- **Prioridades**: urgente, alta, média, baixa
- **Drag & Drop**: reordenação de tarefas via campo `position`
- **Pomodoro**: timer com foco/pausa curta/pausa longa, feedback pós-sessão, opção de acrescentar tempo extra
- **Fila de tarefas**: preview de próximas tarefas na sidebar
- **Admin**: painel para gerenciar usuários com capacidade de "impersonate"
- **i18n**: interface em português brasileiro
- **Deploy**: documentação para cPanel e configuração Docker (Dockerfile)

## Portas

| Serviço | Porta |
|---|---|
| Frontend (Vite dev) | 5173 |
| Backend (Express) | 3001 (configurável via PORT) |