semillero-special-hotel/docs/AI_DEVELOPER_WORKSTATION.md

AI & Developer Workstation Guide

Variable Remuneration, Compensation, and Commissions System - Hoteles Estelar

---

This document outlines the environment configurations (Development vs. Production), API keys, and recommended AI integration tools (like Model Context Protocol servers) designed to optimize this workspace for AI agents (such as Antigravity-cli / agy) and human developers alike.

---

1. Environment Configurations (.env Blueprints)

The Next.js application separates environment secrets between local active development and production servers.

1.1. Development Environment (.env.development)

This file lives in the root directory during development. It configures connection strings to local/sandbox instances.

# -----------------------------------------------------------------------------
# Database Setup
# -----------------------------------------------------------------------------
# Connection string pointing to your local development PostgreSQL instance.
# Prisma uses this URL to run migrations and execute DB queries.
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/special_hotel_dev?schema=public"

# -----------------------------------------------------------------------------
# Next.js Application Settings
# -----------------------------------------------------------------------------
# The host address of your local Next.js client (default dev port is 3000)
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# Secret token used by NextAuth / custom session helper to sign JWTs.
# Generate a secure key locally using: openssl rand -base64 32
NEXTAUTH_SECRET="dev_secret_jwt_sign_key_change_me_locally"

# -----------------------------------------------------------------------------
# n8n Workflow Engine Integration
# -----------------------------------------------------------------------------
# Webhook URL pointing to your local n8n instance where calculations and 
# AI workflows are executed.
N8N_WEBHOOK_URL="http://localhost:5678/webhook/calculate-commissions"

# Local authorization secret shared between Next.js and n8n.
# Incoming webhooks from n8n calling the Next.js API must provide this token 
# in the 'x-n8n-signature' header.
N8N_WEBHOOK_SECRET="local_shared_signature_to_verify_n8n_callbacks"

---

1.2. Production Environment (.env.production)

Production values are configured inside the live environment (e.g. injected into the container via Dockge).

# -----------------------------------------------------------------------------
# Database Setup
# -----------------------------------------------------------------------------
# Secure production database URL. Must be reachable only within the isolated 
# network environment (e.g. via private container network aliases).
DATABASE_URL="postgresql://postgres:secure_db_prod_pass@postgres-vpn:5432/special_hotel?schema=public"

# -----------------------------------------------------------------------------
# Next.js Application Settings
# -----------------------------------------------------------------------------
# The public or VPN-locked domain resolved by Caddy
NEXT_PUBLIC_APP_URL="https://special-hotel.gaboggamer.online"

# High-entropy random secret key for production JWT signatures.
NEXTAUTH_SECRET="prod_high_entropy_session_secret_key"

# -----------------------------------------------------------------------------
# n8n Workflow Engine Integration
# -----------------------------------------------------------------------------
# Production n8n calculation webhook endpoint (internally routed)
N8N_WEBHOOK_URL="http://n8n:5678/webhook/calculate-commissions"

# Optional application-level security secret.
# NOTE: In production, since Next.js and n8n share a private Docker container 
# network, Caddy blocks all public access to /api/n8n/* endpoints. 
# Because of this network-level isolation, token-based verification is optional 
# but recommended as a defense-in-depth practice.
N8N_WEBHOOK_SECRET="prod_shared_signature_to_verify_n8n_callbacks"

---

2. Optimizing the Workspace for the Antigravity Agent (agy)

To make this codebase highly friendly for the Antigravity agent (agy), you can configure the following Model Context Protocol (MCP) servers. Once registered in the agent's active configuration, agy is equipped to inspect database schemas, view live query states, and debug migrations during the development phase.

2.1. Recommended MCP Servers for agy

A. Prisma Postgres MCP Server (@prisma/mcp)

Exposes tools allowing agy to interact with the database using type-safe schemas.

• Use Case: Allows agy to run schema checks, dry-run validations on schemas, and automatically inspect tables during development.
• Available Tools: ListDatabases, ExecuteSqlQuery, IntrospectSchema, and ExecuteRawSql.
• Harness Registration: Add this to the active MCP server list for the agy agent session:

  "prisma-postgres": {
    "command": "npx",
    "args": ["-y", "@prisma/mcp"],
    "env": {
      "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/special_hotel_dev?schema=public"
    }
  }
  

B. PostgreSQL MCP Server (@modelcontextprotocol/server-postgres)

Provides raw PostgreSQL connection and querying tools.

• Use Case: Enables agy to query migration status, seed verification, and raw audit log verification directly.
• Harness Registration:

  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://postgres:postgres@localhost:5432/special_hotel_dev"]
  }
  

---

3. IDE Rules & Agent Contexts (.cursorrules / .clauderules)

Create a .cursorrules or .clauderules file in the root of the project. This guides the AI agent on architecture rules when editing files.

3.1. Standard Prompts for the Agent:

• Prisma Rule: Always run npx prisma generate after editing schema.prisma. All DB queries must utilize Prisma Client.
• Styling Rule: Do not use utility classes or TailwindCSS. Write Vanilla CSS in <Component>.module.css and import it as local styles. Follow CSS variables from globals.css.
• Calculation Engine Rule: The Next.js API only handles inputs, DB commits, and triggers. Do not write complex multi-step calculation loops inside Next.js; offload these to n8n triggers.
• Auditing Rule: Never write manually triggered audit logging. Use the @explita/prisma-audit-log client extension attached to the prisma instance.