CLProject/copy/Initial_Solution_Proposal.md

# Check List Initial Solution Proposal

## 1. Recommended Starting Point

The strongest initial implementation is an offline-first web application with a thin server-backed configuration layer.

This matches the source document's core constraint set:
- reports must work without permanent internet access,
- templates must be centrally controlled,
- final output remains file-based,
- the architecture must be extendable toward future synchronization.

## 2. Proposed Architecture

### Client application

Build a responsive Progressive Web App using:
- React
- TypeScript
- IndexedDB for offline persistence
- a service worker for application asset caching
- browser-based image processing using Canvas or createImageBitmap
- XLSX generation library
- ZIP generation library

Main client modules:
- template cache module
- dynamic form renderer
- report draft repository
- image processing pipeline
- validation engine
- Excel export mapper
- ZIP packaging module
- sync-ready integration layer placeholder

### Server application

Build a small REST API using:
- Node.js
- Express or Fastify
- MariaDB

Main server responsibilities:
- template CRUD
- template versioning
- lookup management
- validation rule delivery
- image rule delivery
- export configuration delivery
- optional authentication later

The server should not accept completed reports in phase 1.

## 3. Why This Design Fits

This design solves the main business problems without introducing early complexity:
- central governance is handled by the backend,
- offline draft work is handled entirely on the client,
- images are optimized before storage/export,
- ZIP export preserves compatibility with the current file-based process,
- future synchronization can be added without replacing the client-side report model.

## 4. Initial Technical Blueprint

### Frontend structure

Suggested feature-oriented structure:

```text
src/
  app/
  features/templates/
  features/reports/
  features/images/
  features/export/
  features/validation/
  features/dashboard/
  shared/ui/
  shared/lib/
  shared/storage/
  shared/api/
```

Key implementation decisions:
- use template-driven rendering instead of hardcoded forms,
- keep report state normalized by report ID,
- store attachments separately from answer objects in IndexedDB,
- version templates immutably once published,
- separate draft validation from export validation.

### Backend structure

Suggested backend domains:
- templates
- templateVersions
- fields
- lookups
- validationRules
- imageRules
- exportSettings

Recommended principle:
the API should deliver a fully materialized template definition for a chosen version so the client can render forms without additional server joins during report editing.

## 5. Minimal Phase 1 Data Model

### Server-side entities

Recommended MariaDB tables:
- templates
- template_versions
- template_sections
- template_fields
- field_validation_rules
- lookup_sets
- lookup_values
- image_rules
- export_profiles

Important rules:
- only one active version per template for new report creation,
- old versions remain readable for existing drafts,
- template JSON snapshots can be generated and cached for fast client download.

### Client-side entities

Recommended IndexedDB stores:
- templatesCache
- reports
- reportAnswers
- attachments
- appConfig

Example report aggregate:

```json
{
  "id": "local-report-uuid",
  "reportNumber": "QC-2026-0001",
  "templateId": "incoming-inspection",
  "templateVersion": 3,
  "status": "in_progress",
  "header": {
    "supplier": "ACME",
    "inspectionDate": "2026-04-09"
  },
  "createdAt": "2026-04-09T09:00:00Z",
  "updatedAt": "2026-04-09T10:15:00Z"
}
```

Example attachment metadata:

```json
{
  "id": "attachment-uuid",
  "reportId": "local-report-uuid",
  "fieldId": "damage-photo",
  "originalFilename": "IMG_0412.jpg",
  "generatedFilename": "QC-2026-0001_SEC01_001.jpg",
  "mimeType": "image/jpeg",
  "width": 1600,
  "height": 1200,
  "sizeBytes": 245312
}
```

## 6. Recommended API Surface

Initial REST endpoints:
- `GET /api/templates`
- `GET /api/templates/:templateId`
- `GET /api/templates/:templateId/versions/:version`
- `GET /api/lookups`
- `GET /api/config/image-rules`
- `GET /api/config/export`
- `GET /api/app-config`

Optional later endpoints:
- `POST /api/auth/login`
- `POST /api/report-uploads`

API response strategy:
- return explicit version metadata with every template,
- include cache timestamps or ETags,
- support incremental refresh later if template volume grows.

## 7. Core User Flow

Phase 1 flow should be:
1. User opens the app online.
2. App downloads active templates and configuration.
3. Data is cached locally.
4. User creates or resumes a report.
5. Report is auto-saved into IndexedDB.
6. Images are validated, optimized, renamed, and stored locally.
7. User marks the report ready for export.
8. Full validation runs.
9. App generates XLSX.
10. App packages XLSX and images into a ZIP and downloads it locally.

## 8. Delivery Plan

### Iteration 1
- define template JSON contract,
- define MariaDB schema,
- implement template read API,
- build application shell and offline cache,
- build report dashboard and draft persistence.

### Iteration 2
- implement dynamic checklist renderer,
- implement draft save and resume,
- implement report switching and status management,
- implement export-readiness validation.

### Iteration 3
- implement image attach, preview, compression, and renaming,
- implement XLSX mapping,
- implement ZIP export,
- run pilot tests on Windows, Android, and iOS.

### Iteration 4
- harden error handling,
- tune storage usage,
- add admin-facing template maintenance workflow,
- prepare phase 2 synchronization extension points.

## 9. Open Gaps That Still Need Definition

The source document is strong at the concept level, but these items still need explicit specification before implementation starts:
- exact template JSON schema,
- exact report numbering strategy,
- exact Excel layout and formatting rules,
- rule language for conditional validation,
- whether PWA installation is required or optional,
- retention and deletion rules for local drafts,
- browser support baseline and test matrix,
- authentication requirements for template administration.

## 10. Main Risks and Mitigations

### Risk: local draft loss
Mitigation: auto-save, visible save state, export reminders, later import/export backup feature.

### Risk: storage pressure from images
Mitigation: enforce compression rules, cap attachment count where needed, show storage usage warnings.

### Risk: template drift
Mitigation: immutable template versions and version-bound drafts.

### Risk: export mismatch with current Excel expectations
Mitigation: validate the XLSX output format early using sample reports before full UI completion.

## 11. Final Recommendation

Proceed with a phase 1 implementation based on:
- React + TypeScript PWA frontend,
- IndexedDB local persistence,
- Node.js REST backend,
- MariaDB template repository,
- local XLSX and ZIP export.

This is the lowest-risk path that still satisfies the documented requirements and preserves a clean path to later server-side synchronization.

## 12. Best Immediate Next Steps

The next concrete deliverables should be:
1. template JSON schema,
2. MariaDB schema draft,
3. API contract draft,
4. report and attachment IndexedDB schema,
5. one sample export template in XLSX format,
6. a first implementation backlog split into frontend and backend work items.