fasto/GEMINI.md

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.
• 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.
• Premium "Onyx & Gold" UI/UX: Completely redesigned the dark mode using a true neutral Charcoal (Zinc) palette, high-contrast text, and brand Yellow accents.
• Dynamic KPI Dashboard: Implemented true period-over-period trend calculations for Leads, Quality Scores, and Response Times.
• Secure File Uploads: Profile avatars are now securely uploaded using multer with strict mimetype validation (JPG/PNG/WEBP), 2MB size limits, and UUID generation to prevent path traversal.
• Enhanced Security Flows:
  • User routing uses secure slugs instead of exposing raw UUIDs.
  • All password reset and setup tokens strictly expire in 15 minutes and are destroyed upon use.
  • Separated the "Reset Password" and "Setup Account" (for new admins) flows for better UX.

🛠 Architecture

• Frontend: React 19, TypeScript, Vite, TailwindCSS (CDN).
• Backend: Node.js, Express, MySQL2 (Pool-based).
• 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:

cp .env.example .env

Ensure you set the database credentials (DB_NAME=fasto_db for production) and GITEA_RUNNER_REGISTRATION_TOKEN.

2. Database

The project expects a MySQL database. The docker-compose.local.yml initializes it with agenciac_comia.sql. Note for Production: If migrating from an old version, you must manually run the SQL to create the password_resets and pending_registrations tables, or rebuild the volume.

3. Running Locally (Docker Compose)

To start the application and database locally:

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.