Application reference. This is an illustrative architecture and scope checklist, not a verified customer project or measured deployment. Technologies, integration scope and delivery items are agreed for the actual brief.
Scenario and Constraints
A factory replacing spreadsheet production tracking. The decisive requirement is two-way traceability: given a finished serial number, list every material lot that went into it, and given a defective material lot, list every finished unit affected. That requirement dictates the data model — it cannot be bolted on later without reprocessing history.
Architecture
Layers and responsibilities
| Layer | Technology | What it is responsible for |
|---|---|---|
| Office web | Vue 3 + Element Plus | Order release, BOM maintenance, scheduling, quality review and reporting. |
| Shop-floor client | Android handheld / tablet (Kotlin), offline-capable | Scan-driven reporting at each station. Designed for gloved hands and poor Wi-Fi: large targets, few taps, local queue. |
| API | Go + Gin | Reporting validation against routing, material consumption rules, traceability queries. |
| Storage | MySQL | Orders, routing, reporting records and lot genealogy. |
| Device gateway | MQTT or OPC UA bridge (optional) | Pulls counts or measurements from equipment where the vendor exposes an interface, normalised into the same reporting tables. |
| Reporting | Scheduled aggregation jobs | Yield, cycle time and station load precomputed, because these queries scan too much history to run live on every dashboard load. |
Data Model
The tables below carry the rules that everything else depends on. Getting these wrong is what turns a working demo into a system that cannot be extended.
Core entities
| Entity | Key fields, relations and rules |
|---|---|
| item / bom | Multi-level bill of materials with effective dates and substitution rules. BOM versions are kept, not overwritten, so an order built last month still resolves against the BOM it actually used. |
| work_order / routing_step | The order and its ordered list of operations, each bound to a work centre with standard time and the reporting rules for that step. |
| production_report | Per-station output: operator, start and finish time, good quantity, rework and scrap with reason codes. This is the input every metric derives from, so its validation rules matter more than the dashboards. |
| material_lot / lot_consumption | Received lots and their issue against a work order. lot_consumption is the join that makes genealogy possible — without it, traceability degrades to guesswork. |
| serial / genealogy | Serialised finished units linked to their consumed lots, forming the graph that answers both trace directions. |
| inspection / defect | Inspection points, sampling rule, defect codes and disposition (accept, rework, scrap), each tied back to the report that produced the unit. |
Key Interfaces
Endpoints that carry the business rules
| Endpoint | Purpose and concurrency notes |
|---|---|
| POST /api/v1/reports | Station reporting. Validates that the previous routing step is complete, that reported quantity does not exceed released quantity, and that material consumption is within tolerance of the BOM — rejecting bad input here is what keeps the reporting data trustworthy. |
| POST /api/v1/reports/batch | Offline queue upload from handhelds, deduplicated on a client UUID, preserving capture time. |
| GET /api/v1/trace/forward/{lot} | Given a material lot, returns every affected finished serial — the query a recall depends on. |
| GET /api/v1/trace/backward/{serial} | Given a finished serial, returns the full material lot genealogy. |
| POST /api/v1/work-orders/{id}/release | Releases an order, snapshotting the BOM and routing version so later master-data edits cannot rewrite history. |
Technical Decisions
- Genealogy modelled from the start. Retrofitting traceability means historical data can never be traced. If traceability is a possible future requirement, the lot_consumption join has to exist from the first release even if the reports come later.
- BOM and routing snapshotted at order release. Master data changes constantly; orders must keep resolving against the version they were released with, or cost and consumption variance become meaningless.
- Validation at the reporting endpoint, not in the dashboard. Metrics computed from unvalidated input produce confident, wrong numbers. Rejecting an impossible report at entry is cheaper than explaining a bad yield figure later.
- Offline queue on the handheld. Factory Wi-Fi has dead zones near metal and machinery. Reporting that fails in those zones simply will not be done, and the data set silently develops holes.
- Coexist with the existing ERP rather than replace it. Compare a scoped interface for orders and inventory movements with an ERP migration using the actual dependencies, costs and risks; confirm the finance workflow before choosing.
Hypothetical Design Targets
The figures below are hypothetical capacity-planning examples, not measured client results, a validated sizing recommendation or an SLA. Set project-specific acceptance targets after defining the workload, devices, data, hardware and third-party dependencies; verify them through a pilot and load tests before committing to a production target.
Capacity and performance targets
| Target | Value and assumption |
|---|---|
| Scan-to-confirm | Hypothetical goal: local feedback under 1 second for a defined report and device. Persist queued records and distinguish local acknowledgement from server acceptance; test network delays and failures. |
| Traceability query | Both directions return within a few seconds for typical genealogy depth, using indexed lot and serial joins; deep multi-level assemblies are validated against your real data during acceptance. |
| Reporting dashboard | Served from precomputed aggregates refreshed on a schedule agreed with operations, rather than scanning raw reports on every page load. |
| Offline tolerance | A full shift of reports queued locally and uploaded on reconnection, deduplicated on the client UUID. |
What Delivery Includes
- Office web source, Go backend source and Android shop-floor client source in your repository
- Database schema with BOM versioning and genealogy tables documented, plus migration history
- API documentation including the offline upload contract and reporting validation rules
- ERP interface specification and the agreed exchange format
- Deployment notes, backup and restore procedure, and label or scanner hardware configuration notes
Planning This for Your Business
The modules above are a starting point, not a fixed package. We normally cut the first release to one core workflow plus one admin workflow, then extend once real usage shows where the load and the edge cases actually are. Send a scoped brief and we will map it against this architecture and tell you which parts you do not need yet.