Stage after merging with project files
This commit is contained in:
Stan
@@ -1,46 +1,146 @@
|
||||
# CLProject Development Environment
|
||||
# Check List Proof of Concept
|
||||
|
||||
This workspace now contains a containerized local development setup based on Node.js, MariaDB, phpMyAdmin, Docker Compose, and VS Code Dev Containers.
|
||||
This repository contains a minimal proof-of-concept backend for the Check List hybrid reporting solution described in the project documentation.
|
||||
|
||||
## Services
|
||||
## What is included
|
||||
|
||||
- `app`: Node.js development container built from `bitnami/node`
|
||||
- `db`: MariaDB container built from `bitnami/mariadb`
|
||||
- `phpmyadmin`: phpMyAdmin container for database inspection
|
||||
- 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
|
||||
|
||||
## Open In VS Code
|
||||
## Scope of this PoC
|
||||
|
||||
1. Open this workspace in VS Code.
|
||||
2. Run `Dev Containers: Reopen in Container`.
|
||||
3. Wait for the `app` service to install dependencies and start the server.
|
||||
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
|
||||
|
||||
The mounted workspace remains editable from VS Code while running inside the container.
|
||||
Not included:
|
||||
- report upload
|
||||
- authentication
|
||||
- admin UI
|
||||
- report draft storage backend
|
||||
- XLSX or ZIP generation
|
||||
- client-side offline application
|
||||
|
||||
## Ports
|
||||
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.
|
||||
|
||||
- App: `http://localhost:3000`
|
||||
## Project structure
|
||||
|
||||
```text
|
||||
.
|
||||
├── .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`
|
||||
|
||||
## Validate The Environment
|
||||
The workspace is bind-mounted into the `app` container, so project files remain editable from VS Code.
|
||||
|
||||
After the containers are up, run:
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
npm run test:environment
|
||||
```
|
||||
|
||||
The test checks that:
|
||||
The test verifies:
|
||||
- the API health endpoint
|
||||
- seeded template data via `/api/templates`
|
||||
- direct MariaDB connectivity
|
||||
- phpMyAdmin availability
|
||||
|
||||
- the Node.js app is reachable
|
||||
- the app can talk to MariaDB
|
||||
- the seed table was created successfully
|
||||
## API endpoints
|
||||
|
||||
## Database Login
|
||||
### Service health
|
||||
|
||||
- Server: `db`
|
||||
- Database: `app_db`
|
||||
- User: `app_user`
|
||||
- Password: `app_password`
|
||||
`GET /api/health`
|
||||
|
||||
Root password is configured in `.env` for local development.
|
||||
### 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`
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
Reference in New Issue
Block a user