# Fasto Project Documentation

## Overview
Fasto is a commercial team management system built with React (Vite) on the frontend and Node.js (Express) on the backend. It uses a MySQL database. It features a complete multi-tenant architecture designed to securely host multiple client organizations within a single deployment.

## 🚀 Recent Major Changes (March 2026)
We have transitioned from a mock-based prototype to a **secure, multi-tenant production architecture**:

- **Multi-Tenancy & Data Isolation:** All backend routes (Users, Teams, Attendances) now strictly enforce `tenant_id` checks. It is technically impossible for one organization to query data from another.
- **God Mode (Tenant Impersonation):** Super Admins can securely impersonate Tenant Admins via a specialized, temporary JWT (`/api/impersonate/:tenantId`). This allows seamless cross-domain support without storing passwords, while strictly maintaining state isolation through forced React reloads and locking mechanisms.
- **Dynamic Funnel Customization:** 
  - Funnel stages are no longer hardcoded ENUMs. Each tenant can create multiple dynamic funnels via the `funnels` and `funnel_stages` tables.
  - Managers can assign specific Teams to specific Funnels.
  - The Dashboard, User Detail, and Attendance Detail pages now dynamically map and color-code stages based on the active team's assigned funnel.
- **Real-Time Notification System:** 
  - Built a persistent notification tray (`/api/notifications`) with real-time polling (10s intervals) and a hidden HTML5 `<audio>` player for cross-browser sound playback.
  - Automated Triggers: Super Admins are notified of new organizations; Tenant Admins/Managers are notified of new user setups; Users are notified of team assignment changes.
- **Role-Based Access Control (RBAC):**
  - **Super Admin:** Global management of all tenants and users (via the hidden `system` tenant).
  - **Admin/Manager:** Full control over members and teams within their specific organization.
  - **Agent:** Restricted access. Can only view their own performance metrics and historical attendances.
- **Enhanced UI/UX:** 
  - Premium "Onyx & Gold" True Black dark mode.
  - Fully collapsible interactive sidebar with memory (`localStorage`).
  - Action buttons across all data tables are permanently visible for faster discoverability (removed hover requirements).
  - Loading states embedded directly into action buttons to prevent double-submissions.
- **Secure File Uploads:** Profile avatars use `multer` with strict mimetype validation (JPG/PNG/WEBP), 2MB size limits, and UUID generation.

## 📌 Roadmap / To-Do
- [ ] **n8n / External API Integration (Priority 1):** 
  - Create an `api_keys` table to allow generating persistent, secure API keys for each Tenant.
  - Build `GET /api/integration/users` so n8n can map its chat agents to Fasto's internal `user_id`s.
  - Build `POST /api/integration/attendances` to allow n8n to programmatically create new attendances linked to specific tenants and users.
- [ ] **Sales & Quality Notification Triggers:** Implement backend logic to automatically notify Managers when an attendance is marked as "Won" (Ganhos), receives a critically low quality score, or breaches a specific Response Time SLA.
- [ ] **Data Export/Reporting:** Allow Admins to export attendance and KPI data to CSV/Excel.
- [ ] **Billing/Subscription Management:** Integrate a payment gateway (e.g., Stripe/Asaas) to manage tenant trial periods and active statuses dynamically.

## 🛠 Architecture
- **Frontend**: React 19, TypeScript, Vite, TailwindCSS (CDN), Recharts, Lucide React.
- **Backend**: Node.js, Express, MySQL2 (Pool-based), Nodemailer.
- **Database**: MySQL 8.0 (Schema: `fasto_db`).
- **Deployment**: Docker Compose for local development; Gitea Actions for CI/CD pushing to a Gitea Registry and deploying via Portainer webhook.

## 📋 Prerequisites
- Docker & Docker Compose
- Node.js (for local development outside Docker)

## ⚙️ Setup & Running

### 1. Environment Variables
Copy `.env.example` to `.env` and adjust values:
```bash
cp .env.example .env
```
*Note:* The backend automatically strips literal quotes from Docker `.env` string values (like `SMTP_PASS`) to prevent authentication crashes.

### 2. Database
The project expects a MySQL database. The `docker-compose.local.yml` initializes it. The Node.js backend automatically runs non-destructive schema migrations on startup (adding tables like `notifications`, `funnels`, `funnel_stages`, and modifying `attendances`).

### 3. Running Locally (Docker Compose)
To start the application and database locally:
```bash
docker-compose -f docker-compose.local.yml up -d --build
```
- **App**: http://localhost:3001
- **Database**: Port 3306

### 4. Gitea Runner
The `docker-compose.yml` includes a service for a Gitea Runner (`fasto-runner`).
- Persistent data is in `./fasto_runner/data`.

## 🔄 CI/CD Pipeline
The project uses Gitea Actions defined in `.gitea/workflows/build-deploy.yaml`.
- **Triggers**: Push to `main` or `master`.
- **Steps**:
    1. Checkout code.
    2. Build Docker image.
    3. Push to `gitea.blyzer.com.br`.
    4. Trigger Portainer webhook.

## 💻 Development
The Dockerfile uses a unified root structure. Both the frontend build and the backend Node.js server are hosted from the same container image.