# 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.