acs/docs/node-migration-plan.md

ACS Node.js Migration Plan

Goal

Convert ACS from the current Spring Boot backend deployment model to an AI DEV compliant Node.js application.

The target deployment must:

• Run as a Node.js app.
• Run on port 3000.
• Use process.env.DATABASE_URL supplied by .project-env / AI DEV.
• Avoid self-managed PostgreSQL containers in the deployment path.
• Build through the root Dockerfile.
• Preserve the existing React frontend where possible.
• Preserve the current /api contract and response envelope:

{ "code": 200, "message": "OK", "data": {} }

Target Architecture

Node.js app
├─ /api/*                  Express API
├─ /assets, /index.html    Static React build from frontend/dist
├─ PostgreSQL              process.env.DATABASE_URL
└─ migrations              SQL files adapted from existing Flyway migrations

Recommended stack:

• Runtime: Node.js + TypeScript
• HTTP: Express
• Database: pg
• Session: express-session with PostgreSQL-backed store
• Password hashing: bcrypt
• QR generation: qrcode
• Excel import/export: multer + exceljs
• Frontend: existing React/Vite app

Migration Principles

1. Keep the frontend API surface stable.
2. Reuse the current PostgreSQL schema as much as possible.
3. Convert by feature slice, not by framework layer.
4. Keep Spring Boot code available as the behavior reference until parity is verified.
5. Make AI DEV deployment simple: npm install, npm run build, npm start.

Feature Migration Order

Phase 1. Node Foundation

• Add root Node package and TypeScript config.
• Add server/ source tree.
• Add env loader for local .project-env compatibility.
• Add PostgreSQL connection pool using DATABASE_URL.
• Add migration runner using SQL files in migrations/.
• Add health check endpoint: GET /api/health.
• Add AI DEV health check endpoint: GET /healthz.
• Add AI DEV DB check endpoint: GET /db.
• Add S3 status endpoint: GET /s3 with an explicit skip response because ACS does not use S3/MinIO.
• Serve frontend/dist for non-API routes.

Phase 2. Auth and Common Infrastructure

• Implement API response helper.
• Implement error handler.
• Implement session middleware.
• Implement role guard middleware.
• Implement:
  • POST /api/auth/login
  • POST /api/auth/logout
  • GET /api/auth/me
  • POST /api/auth/change-password

Phase 3. Read-First Business APIs

• GET /api/zones
• GET /api/visit-requests
• GET /api/visit-requests/pending
• GET /api/visit-requests/:id
• GET /api/stats/summary

Phase 4. Visit Request and Approval Workflow

• POST /api/visit-requests
• POST /api/visit-requests/:id/cancel
• POST /api/approvals/:id/approve
• POST /api/approvals/:id/reject
• Generate qr_token on approval.
• Insert approval and audit log records.
• Preserve "notification failure must not rollback approval" behavior.

Phase 5. Pass, QR, and Access Control

• GET /api/passes/:id
• GET /api/passes/:id/qr.png
• GET /api/public/passes/:token
• GET /api/public/passes/:token/qr.png
• POST /api/access/check-in
• POST /api/access/check-out
• GET /api/access/inside
• GET /api/access/today
• Public kiosk check-in/out endpoints.

Phase 6. Admin Features

• Blacklist CRUD.
• Audit log list.
• Delivery outbox list and retry.
• Excel upload for visit requests.
• XLSX visit report download.

Phase 7. Deployment Cleanup

• Update README and AI DEV run instructions.
• Mark Spring Boot backend and Docker Compose deployment as legacy.
• Keep or remove legacy files after user confirmation.
• Verify deployment in AI DEV with real .project-env.

API Compatibility Rules

• Keep /api prefix.
• Keep frontend DTO field names in camelCase.
• Keep HTTP status behavior close to the Spring implementation:
  • 400 validation error
  • 401 unauthenticated
  • 403 forbidden
  • 404 missing resource
  • 409 business conflict
• State-changing APIs must require an authenticated session unless they are public token endpoints.
• Public pass endpoints must not require login.

Database Migration Strategy

Existing files:

• V1__init.sql
• V2__audit_log.sql
• V3__pass_delivery.sql
• V4__visit_request_contact_fields.sql

Node target:

• Copy SQL into migrations/001_init.sql etc.
• Create a schema_migrations table.
• Apply migrations in filename order.
• Do not create or manage a PostgreSQL container.
• Use only DATABASE_URL.

Verification Checklist

• npm run typecheck
• npm run build
• npm run db:check in AI DEV/Coder with .project-env loaded
• npm run minio:check returns a documented skip because ACS does not use S3
• npm start
• GET /healthz
• GET /db
• GET /api/health
• Login with seeded admin user.
• Create visit request.
• Approve request and confirm QR token.
• Open public pass page.
• Check in and check out.
• Confirm inside/today access views.
• Confirm blacklist blocks check-in.
• Download report XLSX.

Open Decisions

• Exact AI DEV Node version.
• Whether AI DEV automatically runs npm run build or only npm start.
• Whether .project-env exists in the repository root or must be sourced by the shell before startup.
• Whether the production app should seed initial users automatically or require an explicit seed command.