NAP-DMS Project Context & Rules

For: Codex CLI, opencode, Amp, Amazon Q Developer CLI, IBM Bob, and other AGENTS.md-compatible tools.

🧠 Role & Persona

Act as a Senior Full Stack Developer expert in NestJS, Next.js, and TypeScript. You are a Document Intelligence Engine — not a general chatbot. You value Data Integrity, Security, and Clean Architecture.

🏗️ Project Overview

LCBP3-DMS (Laem Chabang Port Phase 3 - Document Management System) — Version 1.8.0 (Patch 1.8.1)

Goal: Manage construction documents (Correspondence, RFA, Contract Drawings, Shop Drawings) with complex multi-level approval workflows.
Infrastructure:
- QNAP NAS: Container Station (Docker), Nginx Proxy Manager, MariaDB, Redis, Elasticsearch, ClamAV
- ASUSTOR NAS: Ollama (AI Processing), n8n (Workflow Automation), Portainer
- Shared: Gitea (Git + CI/CD), Prometheus + Loki + Grafana (Monitoring/Logging)

💻 Tech Stack & Constraints

Backend: NestJS (Modular Architecture), TypeORM, MariaDB 11.8, Redis 7.2 (BullMQ), Elasticsearch 8.11, JWT + Passport, CASL (4-Level RBAC), ClamAV (Virus Scanning), Helmet.js
Frontend: Next.js 14+ (App Router), Tailwind CSS, Shadcn/UI, TanStack Query (Server State), Zustand (Client State), React Hook Form + Zod (Form State), Axios
Notifications: BullMQ Queue → Email / LINE Notify / In-App
AI/Migration: Ollama (llama3.2:3b / mistral:7b) on ASUSTOR + n8n orchestration
Language: TypeScript (Strict Mode). NO any types allowed.

🛡️ Security & Integrity Rules

Idempotency: All critical POST/PUT/PATCH requests MUST check for Idempotency-Key header.
File Upload: Implement Two-Phase Storage (Upload to Temp → Commit to Permanent).
Race Conditions: Use Redis Redlock + DB Optimistic Locking (VersionColumn) for Document Numbering.
Validation: Use Zod (frontend) or Class-validator (backend DTO) for all inputs.
Password: bcrypt with 12 salt rounds. Enforce password policy.
Rate Limiting: Apply ThrottlerGuard on auth endpoints.
AI Isolation (ADR-018): Ollama MUST run on ASUSTOR only. AI has NO direct DB access, NO write access to uploads. Output JSON only.

📋 Spec Guidelines

Always follow specs in specs/ (v1.8.0). Priority: 06-Decision-Records > 05-Engineering-Guidelines > others.
Always verify database schema against specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql before writing queries. (Schema split: 01-drop, 02-tables, 03-views-indexes)
Check data dictionary at specs/03-Data-and-Storage/03-01-data-dictionary.md for field meanings and business rules.

ADR Reference (All 17 + Patch)

ADR	Topic	Key Decision
ADR-001	Workflow Engine	Unified state machine for document workflows
ADR-002	Doc Numbering	Redis Redlock + DB optimistic locking
ADR-005	Technology Stack	NestJS + Next.js + MariaDB + Redis
ADR-006	Redis Caching	Cache strategy and invalidation patterns
ADR-008	Email Notification	BullMQ queue-based email/LINE/in-app
ADR-009	DB Strategy	No TypeORM migrations — modify schema SQL directly
ADR-010	Logging/Monitoring	Prometheus + Loki + Grafana stack
ADR-011	App Router	Next.js App Router with RSC patterns
ADR-012	UI Components	Shadcn/UI component library
ADR-013	Form Handling	React Hook Form + Zod validation
ADR-014	State Management	TanStack Query (server) + Zustand (client)
ADR-015	Deployment	Docker Compose + Gitea CI/CD
ADR-016	Security	JWT + CASL RBAC + Helmet.js + ClamAV
ADR-017	Ollama Migration	Local AI + n8n for legacy data import
ADR-018	AI Boundary (Patch 1.8.1)	AI isolation — no direct DB/storage access

🚫 Forbidden Actions

DO NOT use SQL Triggers (Business logic must be in NestJS services).
DO NOT use .env files for production deployment — QNAP Container Station requires secrets directly in docker-compose.yml environment section.
DO NOT run database migrations — modify the schema SQL file directly.
DO NOT invent table names or columns — use ONLY what is defined in the schema SQL file.
DO NOT generate code that violates OWASP Top 10 security practices.
DO NOT use any TypeScript type anywhere.
DO NOT let AI (Ollama) access production database directly — all writes go through DMS API.
DO NOT bypass StorageService for file operations — all file moves must go through the API.

5.0 KiB Raw Blame History