# ParkFlow — confirmed product decisions

This is the authoritative product record for the sixteen-developer ParkFlow cycle.

## Product purpose

ParkFlow is a read-only analytics and visualization platform for an owner who manages multiple automated parking facilities. Existing parking systems periodically send logs to a ParkFlow API. ParkFlow validates and normalizes the data, then helps the owner and facility managers understand capacity, usage, customer flow, pricing, equipment behavior, queues, and operational performance.

ParkFlow never controls robots, elevators, gates, platforms, PLCs, or other physical equipment.

## Users and access

- Portfolio owner: sees one parking facility in the MVP, can use every dashboard and report, upload data, inspect import errors, configure facility structure and vehicle restrictions, and manage facility-manager accounts.
- Facility manager: sees only the assigned facility, can use dashboards, session and equipment analysis, reports, and uploads, but cannot configure facility structure or manage users.
- The data model remains ready for one owner to manage multiple facilities later, but the MVP interface does not require portfolio comparison.
- Maintenance data may be analyzed, but maintenance is not a separate MVP role.

## Existing systems outside ParkFlow

The supplied document `Depark Application Development Requirements Document OPC-UA and WEB-API.pdf` describes an already-built cross-platform OPC-UA/Web API bridge. It is context only and is not part of the junior project.

ParkFlow starts at the external API:

```text
Existing parking/PLC connector -> ParkFlow ingestion API -> normalized events -> analytics dashboards
```

No OPC-UA client, local bridge, PLC node configuration, or write-back belongs to ParkFlow.

## Data ingestion

- Support one-event and batch ingestion through JSON APIs.
- Provide an MVP upload screen for CSV and JSON files so the system can be demonstrated without an external connector.
- The MVP accepts documented canonical ParkFlow JSON and CSV templates; arbitrary vendor column mapping and vendor-specific adapters are outside core scope.
- Both API endpoints and file imports normalize into the same canonical event shape.
- Every canonical event requires event ID, facility ID, event type, and occurrence time.
- Vehicle and parking-session events additionally require a licence plate. Equipment, space, and system events require no plate unless they are associated with a vehicle.
- External session ID, location, equipment, request/movement ID, vehicle dimensions, pricing, fault details, source system, and extra metadata are conditionally optional.
- ParkFlow always creates a stable internal session ID. When no external session ID exists, it correlates vehicle events by licence plate and journey timing; ambiguous events remain visible and are flagged rather than silently assigned.
- Batch replay must be idempotent and must not duplicate activity; event identity is unique within a facility.
- Most event categories and fields are optional because installations expose different data.
- Missing event types disable dependent metrics gracefully; ParkFlow never invents unavailable measurements.
- Incomplete journeys remain visible as partial sessions with explicit missing-stage flags; ParkFlow does not reject or hide otherwise usable events.
- Each facility should expose a data-coverage/metric-availability view.
- The normal MVP ingestion pattern is weekly or manual data uploads.
- The ingestion architecture must also support more frequent uploads for demonstrations and future installations.
- Near-real-time presentation is optional/bonus if it adds little complexity; it is not critical.
- The initial dashboard must communicate a small number of actionable facts at a glance, without excessive cards, numbers, or clicks.
- Detailed metrics belong in contextual drill-down views reached from the relevant summary, chart, zone, or equipment item.
- The dashboard defaults to the latest 30 days and compares them with the preceding 30 days.
- Event timestamps are displayed and analyzed exactly as uploaded; the MVP performs no timezone conversion.
- The MVP product interface is Hebrew-only and uses a fully right-to-left layout, including charts, tables, navigation, forms, and validation messages.
- The product is desktop-only for the MVP; tablet and mobile responsiveness are not required.

## Initial event categories

All are supported but installations may omit categories:

- Vehicle arrived.
- Parking requested.
- Vehicle accepted at entry bay.
- Vehicle movement started/completed.
- Vehicle stored in a space.
- Retrieval requested.
- Retrieval movement started/completed.
- Vehicle ready for collection.
- Vehicle exited.
- Robot started/stopped/faulted/recovered.
- Elevator started/stopped/faulted/recovered.
- Parking-space status changed.
- System heartbeat/connectivity status.

## Pricing fields

Optional pricing data:

- Pricing type: one-time or monthly subscription.
- Charged amount.
- Currency.
- Subscription/plan identifier.
- Discount amount.
- Payment status.

No card data is needed. The MVP may store the real licence plate plus a stable parking-session ID. Both authorized roles may see and search the full plate in session lists and details; aggregate dashboards do not display individual plates.

## Facility model

ParkFlow must support different automated parking technologies, not only one DE-PARK model. The DE-63 movable-platform system is the primary fixture scenario.

Approved hierarchy:

```text
Portfolio
└── Parking facility
    ├── Access points and kiosks
    ├── Levels
    │   └── Zones
    │       └── Parking spaces
    └── Equipment/assets
        ├── Gates
        ├── Elevators
        ├── Robots
        └── Movable platforms
```

Facilities can omit equipment types. Spaces may define maximum vehicle width, height, and weight.

## Supplied presentation findings

Source: `/Users/shukigur/Downloads/הצגת פתרון החניה.ppsx`

The twelve-slide presentation describes a DE-PARK DE-63 automated movable-platform facility:

1. Licence plate identifies the arriving vehicle.
2. The management system matches the vehicle to a compatible parking position.
3. Vehicle constraints include approximately 200 cm maximum width, position-dependent 165–175 cm height, and 2-ton maximum weight.
4. A screen directs the driver to a floor and zone.
5. While the driver approaches, the system prepares the parking position.
6. The gate opens automatically and the platform waits for the driver.
7. The driver parks and confirms completion on the system screen.
8. Automated platform movement stores the vehicle.
9. For retrieval, the user enters an identifier at a lobby kiosk.
10. Retrieval requests enter a queue when several users arrive together.
11. The system prepares the vehicle and reminds the user where to collect it.
12. Typical position-preparation time is described as about one minute, depending on system size.
13. The presentation states that the exact process may change with design and safety requirements.

Useful analytics therefore include compatible-space assignment, occupancy, floor/zone use, preparation time, parking and retrieval queues, movement duration, throughput, equipment use, faults, recovery, unsuccessful operations, and vehicle-dimension rejection.

## Core metric definitions

- Occupancy: stored vehicles divided by configured usable spaces.
- Parking processing time: vehicle arrival to confirmed storage.
- Retrieval time: retrieval request to vehicle ready for collection.
- Collection time: vehicle ready for collection to facility exit.
- Stored duration: confirmed storage to retrieval request.
- Throughput: completed vehicle exits during the selected period.
- Derived retrieval queue: retrievals requested but not yet ready at a given time.
- Fault downtime: reported fault start to reported recovery.
- Equipment utilization: reported movement time divided by the applicable available period.
- Revenue: sum of reported charges, separated by payment status and pricing type.
- A metric is calculated only when its required events and fields exist, and its data coverage is shown with the result.

## Approved MVP sections

1. Overview.
2. Parking Sessions.
3. Utilization.
4. Customer Flow.
5. Equipment.
6. Revenue.
7. Imports & Data Quality.
8. Reports.
9. Facility Setup.

## Delivery constraints

- Team size: 16 junior developers.
- Schedule: 16 weeks at one development day per week, approximately 16 working days per developer.
- Every developer must fully own one simple, clearly bounded feature that can be explained and demonstrated independently.
- Avoid infrastructure-only assignments and split frontend/backend ownership; each assignment should be a small vertical slice with visible user value.
- Common scaffolding, contracts, fixtures, and integration conventions must be supplied so junior developers can focus on their feature.
- Use the supplied `base-project` foundation: React frontend, Express.js backend, and Supabase database/authentication, with the documented Vercel/Render deployment path.

## Approved ownership map

### Team 1 — Data & Setup

1. Accounts and permissions.
2. Facility setup.
3. Event API and ingestion history.
4. CSV/JSON file imports.

### Team 2 — Parking Journeys

5. Session reconstruction and unmatched-event review.
6. Session search and history.
7. Vehicle journey timeline.
8. Partial-session and data-issue investigation.

### Team 3 — Facility Performance

9. Overview dashboard.
10. Occupancy and capacity.
11. Level, zone, and space visualization.
12. Demand, busy periods, and retrieval queues.

### Team 4 — Business & Reliability

13. Processing-time analysis.
14. Equipment utilization.
15. Faults and downtime.
16. Revenue, data coverage, and management reports.

Each assignment is a full vertical feature with owned data/API behavior, Hebrew interface, fixtures, tests, documentation, handoff, and final demonstration.

## Planning deliverable standard

ParkFlow planning must match the completeness and ownership model established in `medidispatch/`, while using a completely distinct visual design:

- One authoritative decisions document.
- One coherent final acceptance journey in which every developer contributes a visible result.
- Sixteen memorable, individually owned feature assignments grouped into four understandable teams.
- Each assignment defines user value, owned build, output, business rules, dependencies, exclusions, acceptance demonstration, fixtures, tests, documentation, and handoff.
- Each assignment receives sixteen feature-specific weekly goals rather than a generic schedule.
- Fixture-first and contract-first integration allows developers to work before neighboring features are complete.
- Core scope is separated from bonus work.
- The planning website includes architecture, scope, timeline, assignments, team pages, project-owner resources, and copyable verification prompts.
- The Claude Design prompt is stored in `parkflow/claude-design-prompt.md`.
- The reviewed Claude Design output is stored in `parkflow/docs/design/parkflow-product-design.html` and is the approved product reference candidate.
- The artifact covers the full Hebrew RTL desktop navigation, both roles, all core analytical screens, imports, setup, data-coverage patterns, drill-downs, and required failure states without introducing equipment control.
- Juniors should receive reviewed components and tokens extracted from this reference rather than recreate an entire design system.

## Primary fixture facility

Use a fictional Israeli DE-63-inspired facility with three levels, zones A–F, ninety total spaces, several movable-platform units, entry gates, retrieval kiosks, and position-specific vehicle limits. Provide thirty days of deterministic Hebrew-labelled sessions, queues, prices, faults, partial journeys, and intentionally missing telemetry. Use no real customer or driver data.

## Final acceptance journey

1. The owner uploads one week of mixed CSV/JSON parking logs.
2. ParkFlow validates, deduplicates, imports, and explains rejected records.
3. The overview communicates occupancy, demand, retrieval performance, equipment health, revenue, and data freshness at a glance.
4. The owner opens a busy-period analysis and drills into a specific floor and zone.
5. A delayed retrieval is traced through its complete parking-session timeline.
6. ParkFlow relates the delay to a queue and an equipment fault without claiming causation that the events cannot prove.
7. The owner reviews equipment utilization and downtime history.
8. Revenue is broken down by one-time parking and subscriptions.
9. Data-quality views identify unavailable metrics caused by missing telemetry.
10. The owner reviews a filtered on-screen management report; downloading PDF or CSV exports is optional bonus work.
11. A facility manager can analyze and upload data but cannot change facility configuration or manage users.
12. Re-uploading the same source proves that sessions and events are not duplicated.

Every developer must own a visible contribution used in this journey or in one required failure-case demonstration.

## Core and bonus boundary

- Equipment faults are analytical records only: history, frequency, duration, and affected sessions. ParkFlow does not provide notes, acknowledgements, maintenance tasks, assignments, or resolution workflows.
- Automatic rule-based Insights are bonus work, not required for the core MVP.
- Downloadable PDF and CSV report exports are bonus work; the filtered on-screen management report is core.
- Core dashboards still show factual comparisons and drill-downs; they do not automatically interpret or recommend actions.

## Planning status

The product scope, delivery model, ownership map, design reference, contracts, metrics, core/bonus boundary, and final acceptance journey are frozen for plan generation. Changes should be recorded here before assignment contracts are updated.