CLProject/README.md

Check List Proof of Concept

This repository contains a minimal proof-of-concept backend for the Check List hybrid reporting solution described in the project documentation.

What is included

• Node.js REST API for template and configuration delivery
• MariaDB schema for phase 1 configuration data
• seed data with one sample inspection checklist template
• lookup values, image policy, and export profile
• Docker Compose and VS Code Dev Container setup for local development

Scope of this PoC

Included:

• template list endpoint
• active template endpoint
• specific template version endpoint
• lookup endpoints
• image rule endpoint
• export profile endpoint
• generic application config endpoint
• MariaDB schema and seed data

Not included:

• report upload
• authentication
• admin UI
• report draft storage backend
• XLSX or ZIP generation
• client-side offline application

The PoC keeps template content inside a JSON column to reduce initial complexity and speed up delivery. This is deliberate for phase 1 proof-of-concept work.

Project structure

.
├── .devcontainer/
├── docker-compose.yml
├── package.json
├── scripts/
│   └── test-environment.js
├── sql/
│   ├── schema.sql
│   └── seed.sql
└── src/
    ├── app.js
    ├── server.js
    ├── config/
    ├── db/
    ├── middleware/
    ├── routes/
    ├── services/
    └── utils/

Run with Docker and Dev Containers

1. Copy .env.example to .env if you want custom local credentials.
2. In VS Code, run Dev Containers: Reopen in Container.
3. Or start the stack directly with docker compose up -d --build.

Services:

• API: http://localhost:3000
• phpMyAdmin: http://localhost:8080
• MariaDB: localhost:3306

The workspace is bind-mounted into the app container, so project files remain editable from VS Code.

Database bootstrap

On a fresh MariaDB volume, Docker loads sql/schema.sql and sql/seed.sql automatically.

If you already have an older local database volume, either recreate it with docker compose down -v or import the SQL files manually:

docker compose exec -T db sh -lc 'mariadb -uroot -p"$MARIADB_ROOT_PASSWORD" < /docker-entrypoint-initdb.d/schema.sql && mariadb -uroot -p"$MARIADB_ROOT_PASSWORD" < /docker-entrypoint-initdb.d/seed.sql'

Validate the environment

Run the smoke test after the containers are up:

npm run test:environment

The test verifies:

• the API health endpoint
• seeded template data via /api/templates
• direct MariaDB connectivity
• phpMyAdmin availability

API endpoints

Service health

GET /api/health

Templates

• GET /api/templates
• GET /api/templates/incoming-inspection
• GET /api/templates/incoming-inspection/versions/1

Lookups

• GET /api/lookups
• GET /api/lookups/pass-fail

Configuration

• GET /api/config/image-rules
• GET /api/config/export
• GET /api/config/app-config

Example response

GET /api/templates/incoming-inspection

{
  "code": "incoming-inspection",
  "name": "Incoming Inspection Checklist",
  "description": "PoC template for supplier or incoming goods quality inspection.",
  "version": 1,
  "status": "active",
  "publishedAt": "2026-04-09T10:00:00.000Z",
  "definition": {
    "templateId": "incoming-inspection",
    "templateName": "Incoming Inspection Checklist",
    "version": 1,
    "sections": []
  }
}

Recommended next step after this PoC

The next logical implementation layer is the client application that:

• caches templates in IndexedDB,
• renders forms dynamically from definition,
• stores local drafts and image metadata,
• applies validation rules before export,
• generates XLSX and ZIP locally.