mgonzalez/linkedsign
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
linkedsign/AGENT.md
T

6.5 KiB
Raw Permalink Blame History

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
Reference in New Issue View Git Blame Copy Permalink