316 lines
16 KiB
Markdown
316 lines
16 KiB
Markdown
# Architecture and System Design
|
|
|
|
**Variable Remuneration, Compensation, and Commissions System - Hoteles Estelar**
|
|
|
|
---
|
|
|
|
## 1. Technical Stack
|
|
|
|
* **Frontend**: Next.js App Router (React + TypeScript).
|
|
* **Styling**: Vanilla CSS utilizing **CSS Modules** (`*.module.css`) for component-level style isolation, paired with a global variables system (`globals.css`) defining the design tokens.
|
|
* **Backend**: Next.js API Routes (Node.js runtime).
|
|
* **ORM**: Prisma ORM (providing type-safe database queries and automated schema migrations).
|
|
* **Database**: PostgreSQL (decoupled, configured via environment variables to run on any host/network).
|
|
* **Workflow Engine**: **n8n** (external service triggered via API Webhooks). Runs the actual calculation steps, anomaly checks, AI-assisted audits, and notifications. This allows live monitoring of tasks and flexible AI model switching (e.g., swapping OpenAI/Anthropic/Ollama models within n8n nodes without rebuilding the Next.js codebase).
|
|
* **Auditing**: Audit logs are explicitly recorded within transactions inside the Next.js API endpoints (`tx.auditLog.create`) utilizing the authenticated user session details. To enforce financial integrity and SOC 2/GDPR compliance, the database layer implements strict **Row-Level Security (RLS) policies** on the `audit_logs` table that permit only `INSERT` operations (making the logs strictly append-only) and block all `UPDATE` or `DELETE` mutations for all users, including system administrators. Sensitive inputs (like password hashes or detailed bulk data records) are redacted/masked at the application layer before serialization.
|
|
|
|
---
|
|
|
|
## 2. Decoupled Network & Environment Independence
|
|
|
|
The project is structured to run in any isolated Docker environment. All parameters are fed via environment variables to cleanly partition production and development configurations:
|
|
|
|
### 2.1. Environment Variables (.env Layout)
|
|
* **Production Stack Variables (app-prod)**:
|
|
* `DATABASE_URL_PROD`: Connection string for the production PostgreSQL database.
|
|
* `NEXT_PUBLIC_APP_URL`: The production public domain (`https://hotels.gaboggamer.online`).
|
|
* `NEXTAUTH_SECRET`: Secret token used to sign and verify session JWTs in production.
|
|
* `N8N_WEBHOOK_URL`: Webhook endpoint for live production calculation workflows (`https://n8n.gaboggamer.online/webhook/calculate-commissions`).
|
|
* `N8N_WEBHOOK_SECRET`: Signature token to verify n8n webhook payload authenticity.
|
|
* `APP_PROD_INTERNAL_URL`: Internal container URL for prod mapping (`http://special-hotel-prod:3000`).
|
|
* **Development & Test Stack Variables (app-dev)**:
|
|
* `DATABASE_URL_DEV`: Connection string for the development PostgreSQL database.
|
|
* `TEST_DATABASE_URL`: Dedicated connection string for the isolated test/sandbox database.
|
|
* `NEXT_PUBLIC_APP_URL_DEV`: Development URL (`http://localhost:3001`).
|
|
* `NEXTAUTH_SECRET_DEV`: JWT signature token for development sessions.
|
|
* `N8N_TEST_WEBHOOK_URL`: Sandbox webhook URL for development calculation testing (`https://n8n.gaboggamer.online/webhook-test/calculate-commissions`).
|
|
* `N8N_WEBHOOK_SECRET_DEV`: Signature token to authorize development webhook payloads.
|
|
* `APP_DEV_INTERNAL_URL`: Internal container URL for dev mapping (`http://special-hotel-dev:3000`).
|
|
|
|
### 2.2. Component Interaction:
|
|
```mermaid
|
|
graph TD
|
|
User([User Client]) -->|HTTPS| WebApp[Next.js App Router]
|
|
|
|
subgraph Isolated Network
|
|
WebApp -->|Prisma Client| DB[(PostgreSQL Main)]
|
|
WebApp -.->|Prisma Client - Test Env| DBTest[(PostgreSQL Test)]
|
|
WebApp -->|HTTP POST Webhook /webhook-test| n8n[n8n Workflow Engine]
|
|
n8n -->|IF Webhook Path Match| DBTest
|
|
n8n -->|Else| DB
|
|
n8n -->|HTTP POST Callback| WebApp
|
|
end
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Database Schema Design (Entity-Relationship Diagram)
|
|
|
|
```mermaid
|
|
erDiagram
|
|
REGIONS ||--o{ HOTELS : contains
|
|
HOTELS ||--o{ USERS : houses
|
|
USERS ||--o{ GOALS : achieves
|
|
USERS ||--o{ SALES_RESULTS : generates
|
|
USERS ||--o{ SETTLEMENTS : receives
|
|
|
|
COMPENSATION_PLANS ||--o{ CALCULATION_RULES : dictates
|
|
COMPENSATION_PLANS ||--o{ SETTLEMENTS : calculates
|
|
|
|
USERS ||--o{ AUDIT_LOGS : executes
|
|
USERS ||--o{ NOTIFICATIONS : receives
|
|
|
|
REGIONS {
|
|
int id PK
|
|
string name
|
|
string code
|
|
}
|
|
|
|
HOTELS {
|
|
int id PK
|
|
string name
|
|
string code
|
|
int region_id FK
|
|
string status
|
|
}
|
|
|
|
USERS {
|
|
int id PK
|
|
string username
|
|
string email
|
|
string password_hash
|
|
string role "admin | director | hotel_manager | commercial_leader | analyst | auditor | collaborator"
|
|
int hotel_id FK
|
|
string area
|
|
string status "ACTIVE | INACTIVE"
|
|
datetime created_at
|
|
}
|
|
|
|
COMPENSATION_PLANS {
|
|
int id PK
|
|
string name
|
|
string code
|
|
datetime validity_start
|
|
datetime validity_end
|
|
string type "PERCENTAGE | SCALE | CONDITIONAL | FIXED"
|
|
string formula "JSON or string representation"
|
|
decimal meta_amount
|
|
decimal percentage_rate
|
|
decimal max_cap
|
|
string status "DRAFT | ACTIVE | INACTIVE"
|
|
int version
|
|
int created_by FK
|
|
datetime created_at
|
|
}
|
|
|
|
CALCULATION_RULES {
|
|
int id PK
|
|
int plan_id FK
|
|
string type "TIER | BONUS"
|
|
decimal min_achievement "percentage"
|
|
decimal max_achievement "percentage"
|
|
decimal rate "multiplier or percentage"
|
|
decimal payout_amount "fixed payment"
|
|
}
|
|
|
|
GOALS {
|
|
int id PK
|
|
string target_type "INDIVIDUAL | TEAM | HOTEL"
|
|
int target_id "user_id, team_id, or hotel_id"
|
|
string period "YYYY-MM"
|
|
decimal amount
|
|
datetime created_at
|
|
}
|
|
|
|
SALES_RESULTS {
|
|
int id PK
|
|
string source "EXCEL | API"
|
|
int hotel_id FK
|
|
int user_id FK "colaborador"
|
|
string period "YYYY-MM"
|
|
decimal amount
|
|
int sales_count
|
|
string status "PENDING | PROCESSED"
|
|
string idempotency_key UK
|
|
string transaction_id
|
|
int uploaded_by FK
|
|
boolean is_anomaly
|
|
json flagged_reason
|
|
datetime created_at
|
|
}
|
|
|
|
SETTLEMENTS {
|
|
int id PK
|
|
string period "YYYY-MM"
|
|
int plan_id FK "References specific version of the plan"
|
|
int user_id FK
|
|
decimal sales_amount
|
|
decimal goal_amount
|
|
decimal achievement_percentage
|
|
decimal calculated_commission
|
|
decimal calculated_bonus
|
|
decimal adjustment_amount "Clawback or adjustment delta"
|
|
decimal total_payout "calculated_commission + calculated_bonus + adjustment_amount"
|
|
string status "SIMULATED | PENDING | APPROVED | REJECTED"
|
|
int approved_by FK
|
|
datetime approved_at
|
|
string rejection_reason
|
|
int original_settlement_id FK "Self-references the settlement adjusted, if any"
|
|
string adjustment_notes
|
|
boolean ai_audited
|
|
json ai_audit_notes
|
|
datetime created_at
|
|
}
|
|
|
|
AUDIT_LOGS {
|
|
int id PK
|
|
int user_id FK
|
|
string action "CREATE | UPDATE | DELETE | APPROVE | REJECT | LOGIN"
|
|
string target_table
|
|
int target_id
|
|
json previous_value
|
|
json new_value
|
|
string ip_address
|
|
datetime created_at
|
|
}
|
|
|
|
NOTIFICATIONS {
|
|
int id PK
|
|
int user_id FK
|
|
string title
|
|
string message
|
|
string status "UNREAD | READ"
|
|
string type "EMAIL | PUSH"
|
|
datetime sent_at
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Workflows & n8n Integration Model
|
|
|
|
To achieve high modularity, testability, and adaptability, the system implements a **Thick Client (Next.js), Thin Coordinator (n8n)** architecture:
|
|
* **Zero Database Connections in n8n**: n8n must not connect directly to PostgreSQL. All data read/write mutations are handled by Next.js API endpoints.
|
|
* **Minimal Code Blocks in n8n**: Business logic, math calculations, and transaction management are kept on the Next.js side where they are type-safe and fully covered by unit tests.
|
|
* **All AI/LLM inside n8n**: All LLM queries and AI-assisted audits are processed using native n8n LangChain and AI Agent nodes, allowing prompt/model hot-swapping without redeploying the Next.js codebase.
|
|
* **Stalwart Email Notifications**: Email notifications are dispatched directly by n8n using native SMTP nodes configured to use the company's Stalwart mail server.
|
|
|
|
### 4.1. Sales Data Import Workflow
|
|
1. **Trigger**: Next.js calls `POST /webhook/calculate-commissions` (or `/webhook-test/...` in dev) forwarding parsed Excel rows, uploader ID, and an idempotency key.
|
|
2. **n8n Processing**:
|
|
- Queries `POST /api/n8n/validate-sales` to resolve database entities (collaborators, hotels) and retrieve historical standard deviation baselines.
|
|
- Passes data to a native LangChain LLM Chain node (`@n8n/n8n-nodes-langchain.chainLlm`) connected to a **Primary Chat Model** (DeepSeek, `lmChatDeepSeek`) and a **Fallback Chat Model** (Google Gemini, `lmChatGoogleGemini`) to perform semantic anomaly validation and record anomaly flags. If the primary model fails or is rate-limited, n8n automatically falls back to the Google Gemini model.
|
|
- **Dynamic Credential Mapping**: To support isolated project spaces, the bootstrap and test scripts query the n8n API (`GET /api/v1/credentials`) at deploy time, resolve the correct credential IDs for the DeepSeek and Gemini accounts in the workspace, and inject them into the workflow definition before creating or updating the workflow.
|
|
3. **Response**: n8n calls `POST /api/sales/batch-save` (authenticated via `x-n8n-signature`) to persist finalized results in the PostgreSQL database under admin privileges.
|
|
|
|
### 4.2. Settlement Calculation Workflow
|
|
1. **Trigger**: Next.js calls n8n to execute the calculation for period `YYYY-MM`.
|
|
2. **n8n Processing**:
|
|
- Gathers plans, goals, and sales results from `/api/n8n/fetch-calculation-data?period=YYYY-MM`.
|
|
- Offloads calculation processing to `/api/n8n/process-formula` to run the type-safe mathematical rules engine (tiers, bonuses, clawbacks).
|
|
- Runs a native AI Agent node to audit calculated payouts for compliance (e.g. capping rules, negative payouts).
|
|
- Dispatches email alerts using the Stalwart mail server if any extreme payouts require analyst reviews.
|
|
3. **Response**: Persists settlements via `POST /api/n8n/save-settlements` with static signature checks.
|
|
|
|
### 4.3. Test Webhook Branching & Environment Isolation in n8n
|
|
To ensure complete isolation of production data, all n8n workflows follow a strict testing branch architecture:
|
|
1. **Webhook Entry Node**: n8n listens on two webhook path variants:
|
|
- Production calls hit: `/webhook/calculate-commissions` or `/webhook/calculate-settlements`
|
|
- Test suite calls hit: `/webhook-test/calculate-commissions` or `/webhook-test/calculate-settlements`
|
|
2. **Conditional Path Routing**:
|
|
- An `IF` node immediately checks if the webhook request path contains `webhook-test`.
|
|
- **True (Test Mode)**: The workflow sets its Next.js target host variables to the development instance (`https://special-hotel-dev.gaboggamer.online`), which uses `TEST_DATABASE_URL` (the secondary test sandbox database) and signing secret `N8N_WEBHOOK_SECRET_DEV`.
|
|
- **False (Prod Mode)**: The workflow executes against the production instance, validating calls using `N8N_WEBHOOK_SECRET`.
|
|
|
|
---
|
|
|
|
## 5. Security & Access Control Model (RBAC & RLS)
|
|
|
|
We define role-based access restrictions as follows:
|
|
|
|
| Role | Access Level | Restrictions |
|
|
| :--- | :--- | :--- |
|
|
| **Administrador** | Full system write & read. | None. |
|
|
| **Director Comercial** | Reads all dashboards & reports. Can configure metadata. | Cannot calculate or approve. |
|
|
| **Gerente Hotel** | Reads data, sales, and settlements for their specific Hotel. | Restricted to `hotel_id`. |
|
|
| **Líder Comercial** | Triggers simulations, views dashboards. Approves/Rejects settlements. | Restricted to their region/team. |
|
|
| **Analista Financiero** | Reviews calculations. Exports consolidated PDF/Excel reports. | Cannot approve. |
|
|
| **Consulta / Auditor** | Read-only. | No mutations allowed. |
|
|
| **Colaborador** | Consults own history & dashboard. | Restricted to `user_id`. |
|
|
|
|
### 5.1. PostgreSQL Row-Level Security (RLS) & Data Isolation
|
|
To ensure absolute segregation of sensitive compensation data, the database implements **Row-Level Security (RLS)**. RLS is enforced at the database layer (or via Prisma client middleware setting transaction context parameters), guaranteeing security even if application queries omit filters.
|
|
|
|
* **Tenant Isolation Rules**:
|
|
* **Colaboradores**: Can only select rows from `SETTLEMENTS`, `SALES_RESULTS`, and `GOALS` where `user_id = current_setting('app.current_user_id')`.
|
|
* **Gerentes**: Can only select rows where `hotel_id = current_setting('app.current_hotel_id')`.
|
|
* **Líderes**: Can select rows within their assigned regions or teams (`region_id = current_setting('app.current_region_id')`).
|
|
* **Administradores / Analistas**: RLS is bypassed to allow system-wide computations and consolidated reporting.
|
|
* **Audit Trail Immutability**:
|
|
* The `audit_logs` table has database RLS policies (`audit_logs_insert_policy` and `audit_logs_select_policy`) that only permit `INSERT` operations and explicitly block `UPDATE` and `DELETE` actions for all users, including administrators. It is strictly write-only.
|
|
|
|
---
|
|
|
|
## 6. Dual-Environment Docker Deployment Model
|
|
|
|
We design the containerized architecture to run two distinct instances of the application concurrently from the same codebase, ensuring clean division.
|
|
|
|
### 6.1. Service Configurations
|
|
* **Production Container (`app-prod` / `special-hotel-prod`)**:
|
|
* **Network Port**: Exposed on port `3000` (mapped via Caddy to `hotels.gaboggamer.online`).
|
|
* **Database**: Bound to the production `DATABASE_URL_PROD`.
|
|
* **Logs**: Prefixed with `[PROD]` inside the container engine.
|
|
* **Development Container (`app-dev` / `special-hotel-dev`)**:
|
|
* **Network Port**: Exposed on port `3001` (mapped via Caddy to `localhost:3001` or developmental paths).
|
|
* **Database**: Bound to `DATABASE_URL_DEV` (with integration testing executing queries on `TEST_DATABASE_URL`).
|
|
* **Logs**: Prefixed with `[DEV]` for easy debugging contrast.
|
|
|
|
### 6.2. Graceful Dev Failure Model
|
|
The development instance utilizes a validation startup hook. If any development-exclusive environment variables (like `TEST_DATABASE_URL`) are omitted:
|
|
1. The `app-dev` container logs a clear notification: `[DEV] Required development-exclusive variables (TEST_DATABASE_URL, N8N_TEST_WEBHOOK_URL) are missing.`
|
|
2. The entrypoint script exits with **exit code 0**.
|
|
3. Docker or the compose orchestrator registers the container as cleanly stopped (not crashed). The production stack is completely unaffected, avoiding restart-loop penalties or deployment failures.
|
|
|
|
---
|
|
|
|
## 7. Internationalization (i18n) Architecture
|
|
|
|
The internationalization architecture provides bilingual support (English and Spanish) across the application, separating client-side UI translations from AI audit translation flows.
|
|
|
|
### 7.1. Client-Side Translation Context
|
|
* **Scaffolding**: Static JSON dictionaries map UI strings under `src/lib/i18n/dictionaries/`.
|
|
* **State Management**: A React Context provider (`LocaleProvider`) coordinates the selected locale across client components, utilizing local storage for persistence.
|
|
* **Component Translation**: UI components call a lightweight `t(key)` translation hook, dynamically rendering headers, tables, validation warnings, and labels.
|
|
* **Keyword Localization**: Core calculation states and types (such as `ACTIVE/ACTIVO`, `CLOSED/CERRADO`, `REVENUE/INGRESOS`, `NIGHTS/NOCHES`) are mapped at the dictionary level so views translate database enums to localized strings seamlessly.
|
|
|
|
### 7.2. Bilingual AI Audit Translation Flow
|
|
To maintain semantic accuracy and structured parsing within the n8n pipelines, AI audits execute in English, followed by a dedicated translation stage:
|
|
|
|
```mermaid
|
|
graph LR
|
|
Engine[Next.js API] -->|Calculated Data| n8n[n8n Workflow]
|
|
n8n -->|Step 1: Audit in EN| LLM[LLM Node]
|
|
LLM -->|Audit Notes in EN| Trans[LLM Translation Node]
|
|
Trans -->|Translate to EN & ES| Output[Bilingual JSON Object]
|
|
Output -->|Callback Save| NextDb[Next.js Database API]
|
|
```
|
|
|
|
* **Storage**: Localized AI outputs are transmitted as JSON objects:
|
|
```json
|
|
{
|
|
"en": "Audit warning: High commission payout.",
|
|
"es": "Advertencia de auditoría: Pago de comisión alto."
|
|
}
|
|
```
|
|
These are stored in the database as PostgreSQL `JSONB` fields (`flaggedReason` on `SalesResult`, and `aiAuditNotes` on `Settlement`).
|
|
* **Rendering**: The frontend page renders the string corresponding to the user's active locale: `item.aiAuditNotes[locale]`.
|