38eb55793f
All checks were successful
Build and Deploy / build-and-push (push) Successful in 1m52s
- Restricted Agent view to own dashboard and hid management tabs. - Allowed Managers to create teams and members but restricted them from editing roles or emails. - Allowed Admins to update their own email via profile. - Protected Admin roles from being modified by anyone other than Super Admins.
68 lines
3.5 KiB
Markdown
68 lines
3.5 KiB
Markdown
# 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:
|
|
```bash
|
|
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:
|
|
```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.
|