129 lines
6.3 KiB
Markdown
129 lines
6.3 KiB
Markdown
# 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.
|
|
|
|
```bash
|
|
# -----------------------------------------------------------------------------
|
|
# 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).
|
|
|
|
```bash
|
|
# -----------------------------------------------------------------------------
|
|
# 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 AI Agents (Antigravity / agy)
|
|
|
|
To make this codebase highly friendly for AI pair-programming, automated bug-fixing, and system changes, we recommend configuring the following Model Context Protocol (MCP) integrations.
|
|
|
|
### 2.1. Recommended MCP Servers
|
|
|
|
#### A. Prisma Postgres MCP Server (`@prisma/mcp`)
|
|
Exposes tools allowing AI agents to interact directly with the database using type-safe schemas.
|
|
* **Why use it**: Allows the AI agent to run natural language questions (e.g., "Show me the top 5 calculation rules in draft state" or "Run a dry-run check on the user goals schema").
|
|
* **Key capabilities exposed**: `ListDatabases`, `ExecuteSqlQuery`, `IntrospectSchema`, and `ExecuteRawSql`.
|
|
* **Configuration snippet (`mcp.json`)**:
|
|
```json
|
|
"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, high-performance database connectivity tools.
|
|
* **Why use it**: Useful when running migrations or validating raw database logs directly through the AI chat context.
|
|
* **Configuration snippet (`mcp.json`)**:
|
|
```json
|
|
"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.
|