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: Ready-to-use, community-proven @explita/prisma-audit-log Prisma Client Extension. It automatically intercepts database mutations (create, update, delete), tracks changes (old vs new state), handles sensitive field masking (e.g. passwords), and records logs into the AuditLog table. This approach is database-agnostic, requires no native OS dependencies, and runs purely inside the runtime.

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

Core Variables (Both Env):
- DATABASE_URL: Connection string for the active database (Production or Development).
- NEXT_PUBLIC_APP_URL: The domain or local host path of the running application.
- NEXTAUTH_SECRET: Secret key for JWT session validation.
Development-Exclusive Test Variables:
- TEST_DATABASE_URL: Connection string to the secondary sandbox/test database.
- N8N_TEST_WEBHOOK_URL: The n8n testing webhook entry point. Used by development services and test runners.
- N8N_WEBHOOK_SECRET: Token to authorize and verify n8n webhook payload signatures locally.

2.2. Component Interaction:

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)

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 UK
        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
        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
        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

By offloading calculations and integrations to n8n, we achieve a highly visual, modular, and editable workflow architecture.

4.1. Sales Data Import Workflow

Trigger: Next.js calls POST /api/n8n/import-sales which forwards the parsed Excel payload to n8n's webhook URL.
n8n Processing:
- Iterates through sales records.
- Queries Next.js APIs to validate collaborator codes and hotel IDs.
- Cleanses data and identifies duplicates.
- Uses an LLM node (with configurable models: GPT-4, Claude 3.5, Gemini, etc.) to perform semantic anomaly checks (e.g., flag sales values that deviate more than 2.5 standard deviations from the collaborator's monthly average).
Response: n8n POSTs the sanitized/flagged list back to POST /api/sales/batch-save in Next.js to update the database.

4.2. Settlement Calculation Workflow

Trigger: Next.js calls n8n to execute the calculation for period YYYY-MM.
n8n Processing:
- Pulls active plans, individual goals, and actual sales from the Next.js API.
- Evaluates the mathematical formulas.
- Evaluates rule scales and applies caps.
- Generates notifications (via email or push notifications) using n8n integrations.
Response: Updates database records via the Next.js API and completes the task.

4.3. Test Webhook Branching & Database Isolation in n8n

To ensure complete isolation of production data, all n8n workflows must follow a strict testing branch architecture:

Webhook Entry Node: n8n listens on two webhook path variants:
- Production calls hit: /webhook/calculate-commissions
- Test suite calls hit: /webhook-test/calculate-commissions
Conditional Path Routing:
- An IF node immediately checks if the webhook request path contains webhook-test.
- True (Test Mode): The workflow overrides its database credential node configurations to connect to TEST_DATABASE_URL (the secondary test sandbox database) and makes API callbacks back to the Next.js test instance.
- False (Prod Mode): The workflow executes against the main DATABASE_URL and interacts with the production Next.js instance.

5. Security & Access Control Model (RBAC)

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	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 RLS policies that prevent UPDATE or DELETE actions for all users, including administrators. It is strictly write-only (INSERT operations 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):
- Network Port: Exposed on port 3000 (mapped via Caddy to special-hotel.yourdomain.com).
- Database: Bound to the production DATABASE_URL.
- Logs: Prefixed with [PROD] inside the container engine.
Development Container (app-dev):
- Network Port: Exposed on port 3001 (mapped via Caddy to special-hotel-dev.yourdomain.com).
- Database: Bound to TEST_DATABASE_URL (acting as its main DATABASE_URL for test isolated migrations).
- 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:

The app-dev container logs a clear notification: [DEV] Missing required development variables. Gracefully shutting down development service.
The entrypoint script exits with exit code 0.
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.

12 KiB Raw Blame History