Skip to content

Commit 413fcb7

Browse files
Parkly Initcursoragent
Parkly Init
and
cursoragent
committed
chore: Phase 0A truth alignment
- .cursorrules: Node.js 20 LTS → Node.js 22 LTS (CI uses 22, align rules) - README.md: rewrite opening with product truth, add architecture diagram, tech stack table, demo accounts, quickstart, quality gates - HOW_TO_SETUP.md: Node 20.x → 22.x - packages/contracts/README.md: rewrite from "PR-02/PR-04 minimum" to canonical shared transport contracts - .planning/BRUTAL_AUDIT.md: fix stale context (was "no git, no .planning/") Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent b8465d8 commit 413fcb7

5 files changed

Lines changed: 143 additions & 37 deletions

File tree

‎.cursorrules‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Your code must be production-ready, highly optimized, secure, and strictly adher
99
- Optimize for readability, performance, and concurrency safe (avoid race conditions).
1010

1111
## 2. Technology Stack (STRICT)
12-
- **Backend:** Node.js 20 LTS, Express.js 4, TypeScript (Strict Mode).
12+
- **Backend:** Node.js 22 LTS, Express.js 4, TypeScript (Strict Mode).
1313
- **Database:** Prisma 7 ORM, MySQL 8.x, Redis 7 (Cache, Redlock, Rate Limit).
1414
- **Background Jobs:** BullMQ (Outbox pattern, DLQ).
1515
- **Frontend:** React 18, Vite, TanStack Query, Zustand, React Router v6.

‎.planning/BRUTAL_AUDIT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Parkly Repo Audit — Brutal Assessment
22

33
**Audited:** 2026-05-05
4-
**Context:** Brownfield codebase, no git, no `.planning/` directory yet. This audit is the foundation for the GSD roadmap.
4+
**Context:** Brownfield codebase. This audit was created during the initial GSD planning pass and is now committed under `.planning/`. The codebase was audited as-is before any Phase 0 or Phase 1 work began.
55

66
---
77

‎HOW_TO_SETUP.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This file is the short local bootstrap path. Keep it aligned with real scripts,
44

55
## Prerequisites
66

7-
- Node.js 20.x
7+
- Node.js 22.x
88
- pnpm 10.x
99
- Docker Desktop
1010

‎README.md‎

Lines changed: 104 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,128 @@
1-
# Parkly — Gate Operations Monorepo
1+
# Parkly — Parking Operations Command Center
22

3-
Monorepo này đã được cutover từ legacy gate-events flow sang operations console đầy đủ hơn: session orchestration, decision engine, entry/exit workflow, review queue, SSE health feeds, outbox monitor và evidence pack.
3+
Parkly là hệ thống điều hành bãi giữ xe cho nhân viên cổng, giám sát và admin. Nó tập trung vào xe vào/ra, duyệt biển số (ALPR), trạng thái làn/camera, xe đang trong bãi, audit trail, và đồng bộ sự kiện bền vững qua outbox.
4+
5+
Parkly is a parking operations command center for gate operators, supervisors, and admins. It manages entry/exit sessions, ALPR-assisted review, live lane health, active occupancy, audit trails, and resilient outbox delivery.
6+
7+
## What It Does
8+
9+
```
10+
Guard scans plate → System creates session → High confidence: auto-open barrier
11+
→ Low confidence: review queue → Supervisor approves → Barrier opens
12+
Vehicle exits → Session resolved → Audit + outbox events delivered
13+
```
14+
15+
## Core Workflows
16+
17+
| Workflow | Description |
18+
|----------|-------------|
19+
| **Run Lane** | Primary workspace: select site/gate/lane, submit entry or exit capture |
20+
| **Review Queue** | Supervisor reviews low-confidence captures, approves/rejects in seconds |
21+
| **Session History** | Full audit trail with timeline, media, and decision context |
22+
| **Device Health** | Live camera/lane status with heartbeat monitoring |
23+
| **Outbox Monitor** | B2B webhook delivery status, DLQ failures, retry backlog |
24+
25+
## Architecture
26+
27+
```
28+
[Guard Console / Mobile] ──HTTPS──> [Express API]
29+
│
30+
┌─────────────┼─────────────┐
31+
│ │ │
32+
MySQL Redis BullMQ
33+
(Prisma) (Redlock) (Outbox)
34+
│ │ │
35+
└─────────────┼─────────────┘
36+
│
37+
[SSE Streams]
38+
│
39+
[React SPA Console]
40+
```
41+
42+
Key patterns: outbox pattern for resilient external delivery, snapshot REST + SSE delta for real-time state, Redis Redlock for lane coordination, three auth planes (user JWT, device HMAC, service secrets).
43+
44+
## Tech Stack
45+
46+
| Layer | Technology |
47+
|-------|-----------|
48+
| Backend | Node.js 22 LTS, Express 4, TypeScript (Strict) |
49+
| Database | Prisma 7 ORM, MySQL 8.x |
50+
| Cache/Queue | Redis 7, BullMQ |
51+
| Frontend | React 18, Vite, TanStack Query, Zustand, React Router v6 |
52+
| Shared | `@parkly/contracts` (Zod schemas), `@parkly/gate-core` |
53+
| E2E | Playwright |
454

555
## Structure
656

7-
- `apps/api` — Express API, worker, Flyway, Prisma, operational scripts
57+
- `apps/api` — Express API, worker, Flyway migrations, Prisma schema
858
- `apps/web` — React/Vite operations console
9-
- `packages/contracts` — shared Zod contracts/types
59+
- `packages/contracts` — shared Zod transport contracts (single source of truth)
1060
- `packages/gate-core` — shared gate decision / domain helpers
11-
- `docs` — runbook, API surface, evidence pack, archive patch notes
61+
- `docs` — API contract, ADRs, runbook, evidence requirements
1262

1363
## Quickstart
1464

1565
```bash
66+
# 1. Copy env
1667
cp apps/api/.env.example apps/api/.env
1768
cp apps/web/.env.example apps/web/.env
69+
70+
# 2. Install
1871
pnpm install
19-
cd apps/api
20-
pnpm db:migrate
21-
pnpm prisma:pull
22-
pnpm db:grant:app
23-
pnpm db:seed:min
24-
pnpm dev
25-
```
2672

27-
Terminal khác:
73+
# 3. Start infrastructure
74+
docker compose -f infra/docker/docker-compose.local.yml up -d mysql redis
2875

29-
```bash
30-
cd apps/api
31-
pnpm worker:dev
76+
# 4. Setup database
77+
pnpm --dir apps/api db:migrate
78+
pnpm --dir apps/api db:grant:app
79+
pnpm --dir apps/api db:seed:min
80+
81+
# 5. Run
82+
pnpm dev:api # Terminal 1: API on :3000
83+
pnpm --dir apps/api worker:dev # Terminal 2: BullMQ worker
84+
pnpm dev:web # Terminal 3: Web console on :5173
3285
```
3386

34-
Terminal khác nữa:
87+
## Entry Points
88+
89+
| URL | Purpose |
90+
|-----|---------|
91+
| `http://127.0.0.1:5173/` | Web console |
92+
| `http://127.0.0.1:3000/docs` | Swagger API docs |
93+
| `http://127.0.0.1:3000/openapi.json` | OpenAPI spec |
94+
| `http://127.0.0.1:3000/metrics` | Prometheus metrics |
95+
96+
## Demo Accounts
97+
98+
| Role | Username | Password | Default Route |
99+
|------|----------|----------|---------------|
100+
| SUPER_ADMIN | `admin` | `Parkly@123` | /overview |
101+
| MANAGER | `manager` | `Parkly@123` | /review-queue |
102+
| OPERATOR | `ops` | `Parkly@123` | /run-lane |
103+
| GUARD | `guard` | `Parkly@123` | /run-lane |
104+
105+
## Quality Gates
35106

36107
```bash
37-
cd apps/web
38-
pnpm dev
108+
pnpm test:full # Canonical release gate: typecheck + unit + e2e + i18n
109+
pnpm typecheck:api # API TypeScript strict
110+
pnpm typecheck:web # Web TypeScript strict
111+
pnpm --dir apps/web build:web # Production bundle (must pass before release)
39112
```
40113

41-
## Main entry points
114+
CI runs: quality gate, Flyway migration validation, npm audit, dependency review, CodeQL.
115+
116+
## Evidence & Docs
117+
118+
- `docs/PARKLY_GOLDEN_PATH.md` — 3-min + 10-min demo walkthrough
119+
- `docs/API.md` — API contract, envelopes, auth planes, SSE hydration rules
120+
- `docs/ADR.md` — Architecture decision records
121+
- `docs/EVIDENCE.md` — Release evidence requirements
122+
- `.planning/` — GSD project planning (roadmap, requirements, audit)
42123

43-
- API docs: `http://127.0.0.1:3000/docs`
44-
- OpenAPI JSON: `http://127.0.0.1:3000/openapi.json`
45-
- Metrics: `http://127.0.0.1:3000/metrics`
46-
- Web console: `http://127.0.0.1:5173/`
124+
## Roadmap
47125

48-
## Operator docs
126+
7 phases: Truth Alignment → Golden Path → IA/Role Workflow → Industrial Ops UI → Contract Hardening → Playwright Evidence → Portfolio Packaging.
49127

50-
- `docs/RUNBOOK.md`
51-
- `docs/API.md`
52-
- `docs/EVIDENCE.md`
53-
- `docs/README.md`
128+
See `.planning/ROADMAP.md` for full phase details.

‎packages/contracts/README.md‎

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,39 @@
11
# @parkly/contracts
22

3-
Contracts tối thiểu cho PR-02 / PR-04.
3+
Canonical shared Zod schemas and TypeScript types for the Parkly transport layer. Both `apps/api` and `apps/web` consume this package as the single source of truth for API contracts.
44

5-
Có:
6-
- DTO `PlateCanonicalDtoSchema`
7-
- list response schemas cho Site/Gate/Lane
8-
- capture body schemas cho ALPR/RFID/SENSOR/heartbeat
5+
## What It Contains
6+
7+
- **Auth types**: `AuthRole`, session types, JWT claims
8+
- **Gate session types**: `GateSession`, capture request/response, decision codes
9+
- **Review queue types**: `ReviewItem`, claim/approve/reject actions
10+
- **Topology types**: `Site`, `Gate`, `Lane`, `Device`
11+
- **Dashboard types**: `DashboardSummary`, KPI metrics
12+
- **Outbox types**: `OutboxItem`, delivery status
13+
- **Common types**: `PageInfo`, cursor pagination, HTTP envelopes
14+
15+
## RC1 Envelope Format
16+
17+
### Success
18+
```json
19+
{ "requestId": "uuid", "data": {} }
20+
```
21+
22+
### Error
23+
```json
24+
{ "requestId": "uuid", "code": "UPPERCASE_ENUM", "message": "...", "details": {} }
25+
```
26+
27+
## Usage
28+
29+
```typescript
30+
import type { GateSession, AuthRole } from '@parkly/contracts'
31+
import { PlateCaptureBodySchema } from '@parkly/contracts'
32+
```
33+
34+
## Maintenance Rules
35+
36+
- All API routes must use schemas from this package for request validation
37+
- Frontend page components must use types from this package, not duplicated inline
38+
- Error codes must be UPPERCASE_SNAKE_CASE
39+
- Pagination must be cursor-based with `pageInfo.nextCursor`

0 commit comments

Comments
 (0)