# LinkedSign – AI Development Agent (Codex)

## Context
You are working on a full-stack web application called **LinkedSign**, a digital document signing platform using PFX/P12 certificates.

## Tech Stack (MANDATORY)
- Backend: Node.js + Express
- Frontend: React (Vite)
- Database: MariaDB
- Auth: JWT (access + refresh)
- Encryption:
  - bcrypt or argon2 for passwords
  - AES-256-GCM for sensitive data
- Architecture: REST API (frontend/backend separated)

## Environment
- OS: Debian 12 (no GUI)
- IDE: code-server
- Root path: /home/mgonzalez/desarrollo/react/linkedsign/

---

## Global Rules (CRITICAL)

- Always maintain modular architecture (domain-based modules)
- NEVER break existing structure
- Prefer minimal changes over rewrites
- All code must be production-ready
- Always validate inputs
- Always apply security best practices by default
- Always log critical actions
- Never expose secrets in code
- Use environment variables (.env)

---

## Backend Architecture

Each module must follow:

controller → service → repository → routes → validator

Modules:

- auth
- users
- subscriptions
- documents
- certificates
- signatures
- invitations
- mail
- audit
- legal
- health

---

## Security Requirements

- Rate limiting on login
- Brute-force protection
- Helmet enabled
- CORS restricted
- Input validation (Joi/Zod)
- File validation (PDF only)
- Encrypt:
  - PFX files (or protect access)
  - certificate passwords
- Audit:
  - login attempts
  - IP address
  - timestamps
  - document actions

---

## Storage Rules

- Documents stored in:
  /storage/documentos/YYYY/MM/

- NEVER store files inside database

---

## Frontend Rules

- Use React with modular structure (features-based)
- Responsive UI (mobile + desktop)
- Clean modern UI (prefer Tailwind or clean CSS)
- Use services layer for API calls
- Use hooks for logic reuse

---

## Features to Build

1. Authentication (with email confirmation)
2. Document management (upload, download, delete)
3. Certificate management (PFX/P12)
4. Digital signature (single + multi-user)
5. Invitations (guest signing via link)
6. Audit system
7. Legal acceptance (terms & privacy)

---

## API Requirements

- All endpoints must be documented
- Provide cURL examples for each endpoint
- Use consistent response format:

{
  success: boolean,
  data: any,
  error: string | null
}

---

## Code Quality

- Use async/await
- Use centralized error handling
- Avoid duplicated logic
- Use clear naming conventions

---

## Testing

- Add tests when logic is critical
- Do not break existing functionality

---

## Workflow

Before writing code:

1. Analyze current structure
2. Propose plan
3. Wait for approval (IMPORTANT)
4. Then implement

---

## Language Rules

- Explain in Spanish
- Code in English

---

## Skills Usage (IMPORTANT)

You can use skills when appropriate:

- Use "refactor" skill for improving structure
- Use "security review" skill before finalizing modules
- Use "ui improvement" skill for frontend polishing
- Use "generate tests" skill for critical flows

Always suggest when a skill can be applied.

---

## Goal

Build a secure, scalable, production-ready digital signing platform suitable for multi-user environments and legal compliance.

---

## Guía rápida: nuevo tipo de estampado

Cuando se cree o ajuste un nuevo estampado visual de firma, revisar siempre estas capas:

### 1. Vista previa en configuración

- Archivo: `frontend/src/components/ui/SignatureStylePicker.jsx`
- Aquí se agrega el nuevo estilo al arreglo `STYLES`
- Cambiar:
  - `id`
  - `label`
  - `desc`
  - `preview(...)`

### 2. Vista previa al colocar la firma sobre el PDF

- Archivo: `frontend/src/components/ui/PdfSignaturePlacer.jsx`
- Aquí se dibuja el estampado que el usuario ve antes de firmar
- Cambiar:
  - rama `if (signatureStyle === 'nuevo-estilo')`
  - ancho dinámico si aplica en `getSignatureWidth(...)`
  - partición de nombre o textos fijos si aplica

### 3. Estilos CSS de las vistas previas

- Archivo: `frontend/src/index.css`
- Aquí viven:
  - `.sig-preview-*`
  - `.sp-*`
- Cambiar:
  - borde
  - fondo
  - tipografía
  - separadores
  - layout del QR y textos

### 4. PDF final real que se incrusta al firmar

- Archivo: `backend/src/modules/signing/signing.service.js`
- Este es el archivo clave del sello visible real dentro del PDF
- Cambiar:
  - función nueva tipo `drawStyleNuevo(...)`
  - selección del estilo en `signPdf(...)`
  - helper de líneas/nombre si aplica
  - QR, bordes, divisor, tipografía y textos fijos

### 5. Flujo backend que llama al generador PDF

- Firma normal web:
  - `backend/src/modules/signatures/signatures.service.js`
- Firma por invitación:
  - `backend/src/modules/invitations/invitations.service.js`
- PDF legal firmado:
  - `backend/src/modules/legal/legal.service.js`

Si el estampado no cambia en el PDF final, verificar primero que el flujo usado realmente pase por `backend/src/modules/signing/signing.service.js`.

### 6. Orden correcto de trabajo

1. Ajustar preview en `SignatureStylePicker.jsx`
2. Ajustar preview de estampado en `PdfSignaturePlacer.jsx`
3. Ajustar CSS en `frontend/src/index.css`
4. Ajustar sello PDF real en `backend/src/modules/signing/signing.service.js`
5. Validar:
   - `cd frontend && npm run build`
   - `cd backend && node -e "require('./src/app')"`
6. Si va a producción:
   - `commit`
   - `push`
   - deploy web

### 7. Regla práctica importante

Si el cambio se ve en la web pero no en el PDF firmado:

- casi seguro falta tocar `backend/src/modules/signing/signing.service.js`
- o el backend runtime de producción quedó desalineado respecto a `source`

### 8. Verificación obligatoria en producción para cambios backend

Cuando el cambio afecta el PDF final o cualquier lógica backend:

1. hacer deploy
2. reiniciar `linkedsign-backend`
3. confirmar que el `PID` cambió:
   - `ps -ef | grep 'node .*src/server.js' | grep -v grep`
4. revisar que el proceso activo escucha en `:4000`
5. recién después hacer la prueba funcional

Caso ya confirmado en producción:

- el archivo en disco puede tener el fix correcto
- pero si `linkedsign-backend` no reinicia de verdad, el proceso sigue firmando con código viejo en memoria

### 9. Método recomendado para depurar un estampado nuevo

Si un sello no refleja cambios y hay duda de ruta:

1. agregar una marca visual temporal en `backend/src/modules/signing/signing.service.js`
2. desplegar
3. reiniciar backend y confirmar cambio de `PID`
4. firmar un PDF nuevo
5. comprobar si la marca aparece en el PDF final
6. quitar la marca temporal antes de cerrar el trabajo