GateFlow — The Invisible Sentinel

Enterprise platform for physical access control and marketing intelligence.
Multi-tenant Next.js dashboards, Expo field apps, signed QR flows, and Arabic/English RTL—built for high-trust PropTech (including MENA).

---

💎 The Vision

GateFlow treats every physical arrival as a first-class digital event: signed QR credentials, tenant-safe data, offline-capable scanners, and marketing attribution from ad click to gate entry. The monorepo delivers six coordinated apps—web dashboards, resident surfaces, and native field tools—on one shared design system, schema, and automation toolchain.

---

🗂️ Table of Contents

1. The 6-App Ecosystem
2. Upcoming features
3. Clone, database & run (from GitHub)
4. Master Architecture
5. Strategic Core Pillars
6. Security & Compliance
7. Analytics & Intelligence
8. Localization & i18n
9. The Ralph Loop Automation
10. Performance & Governance
11. Documentation & Support

---

🏗️ The 6-App Ecosystem

GateFlow is a technical monorepo orchestrating six specialized applications, unified by a shared core of design tokens, cryptographic standards, and real-time data flows.

View App Matrix

Application	Role	Key Capability	Deployment
Client Dashboard	Property Hub	Real-time monitoring (SSE), Marketing ROI & CRM.	Vercel
Admin Dashboard	Platform Ops	Multi-tenant isolation & Cloud platform health.	Vercel
Resident Mobile	User Interface	Native iOS/Android pass creation & WhatsApp sync.	App Store/Play
Scanner App	Field Agent	Offline-first HMAC validation & Haptic feedback.	Enterprise Distribution
Resident Portal	Web Access	Guest management & Pass self-service utility.	Vercel
Marketing Site	Growth Node	High-SEO conversion funnels & Tracking events.	Vercel

---

🔮 Upcoming features

Single source of truth: docs/reference/product/UPCOMING.md — active initiatives (with plan links), planning backlog, recently shipped highlights, and Q3 strategic goals.

The README does not duplicate that document. Open UPCOMING.md for tables, sprint status, and initiative detail; refresh this section only when you want a new high-level teaser line here.

Snapshot (see UPCOMING.md for live status): GateFlow Design System completed · Admin Dashboard Evolution (Side Menu & CMS) · resident-portal responsive overhaul · scanner-app onboarding wizards.

---

🚀 Quick Start & Local Development

End state: monorepo root with Node 20+, pnpm, PostgreSQL, root .env.local, generated Prisma Client, schema applied (db push or migrations), and one or more Next.js or Expo dev servers running.

Prerequisites

Requirement	Notes
Node.js ≥ 20	Matches engines in root package.json.
pnpm 8.15	Repo pins packageManager; use Corepack (recommended) or a global install.
PostgreSQL 16+	Local, Docker, or managed (Neon, Supabase, RDS, etc.).
Git	Clone, hooks (Husky), and CI-aligned workflows.

pnpm via Corepack (recommended):

corepack enable
corepack prepare pnpm@8.15.0 --activate

Optional: Bun (used for @gate-access/db tests), Expo Go or simulators for mobile apps.

1. Clone the monorepo

HTTPS

git clone https://github.com/iDorgham/Gateflow.git
cd Gateflow

SSH

git clone git@github.com:iDorgham/Gateflow.git
cd Gateflow

Your folder name may be Gateflow, Gate-Access, or another checkout name—what matters is that package.json and pnpm-workspace.yaml are at the current directory for all commands below.

2. Create a PostgreSQL database

Pick one approach:

Approach	Example
Local CLI	createdb gate_access then build a URL like postgresql://USER:PASSWORD@localhost:5432/gate_access?schema=public
Docker	docker run --name gateflow-pg -e POSTGRES_PASSWORD=dev -e POSTGRES_DB=gate_access -p 5432:5432 -d postgres:16
Hosted	Create a database in your provider’s UI and copy the connection string

Prisma (packages/db/prisma/schema.prisma) uses DATABASE_URL and a directUrl from DIRECT_DATABASE_URL.

• Local Postgres (no Accelerate): set DATABASE_URL and DIRECT_DATABASE_URL to the same direct connection string in root .env.local.
• Prisma Accelerate / pooled URL for runtime: keep DATABASE_URL as the pooled/accelerate URL if your deployment requires it, but set DIRECT_DATABASE_URL to the direct Postgres URL for migrations, db push, and CLI.

See also packages/db/.env.example and Environment variables.

3. Install dependencies

pnpm install

4. Environment variables (minimal mental model)

Variable	Role
DATABASE_URL	App/runtime database access
DIRECT_DATABASE_URL	Prisma migrations & direct CLI (often same as DATABASE_URL locally)
NEXTAUTH_SECRET, NEXTAUTH_URL	Auth for Next.js apps
QR_SIGNING_SECRET	HMAC for QR payloads (must align with scanner EXPO_PUBLIC_QR_SECRET)
ENCRYPTION_MASTER_KEY	Sensitive field encryption

Full matrix, per-app keys, and optional services (Redis, AI, Stripe): ENVIRONMENT_VARIABLES.md and root .env.example.

5. Bootstrap the database (choose one path)

Path A — Automated (recommended)

pnpm setup:dev

scripts/dev/setup-dev.js will, among other steps:

1. Ensure dependencies (pnpm install --frozen-lockfile).
2. Seed root .env.local from .env.example and prompt for critical secrets.
3. Run pnpm db:generate (Prisma Client).
4. Run prisma db push (good for a fresh dev database).
5. Run pnpm check:env --app client (warnings are OK for optional keys).
6. Install Husky hooks.

If DIRECT_DATABASE_URL is missing from .env.local, add it (usually identical to DATABASE_URL for local Postgres).

Path B — Manual

cp .env.example .env.local
# Edit .env.local: DATABASE_URL, DIRECT_DATABASE_URL, NEXTAUTH_*, QR_SIGNING_SECRET, ENCRYPTION_MASTER_KEY, ADMIN_ACCESS_KEY, …
pnpm db:generate
pnpm --filter @gate-access/db exec prisma db push

Versioned migrations (instead of db push):

pnpm --filter @gate-access/db exec prisma migrate dev

Inspect data:

pnpm db:studio

Env layering: root .env / .env.local plus apps/<app>/.env.local (later wins). See scripts/check/check-env.js for how checks resolve files.

App-specific examples: apps/marketing/.env.example, apps/resident-mobile/.env.example.

6. Validate before you run UI

pnpm check:env              # all configured apps
pnpm check:env:client       # client dashboard only
pnpm preflight              # changelog + lint + typecheck + tests (slower CI-like gate)

7. Run development servers

Commands are Turborepo wrappers from root package.json (turbo dev with a filter). pnpm dev runs every workspace that exposes a dev script—heavy on a laptop; prefer filtered commands for day-to-day work.

Command	Turbo / package	What you get	Default URL / notes
pnpm dev	all dev tasks	Parallel dev for the whole monorepo	High CPU/RAM; use when you need everything
pnpm dev:client	client-dashboard	Property / B2B dashboard + API routes	http://localhost:3001
pnpm dev:admin	admin-dashboard	Platform admin	http://localhost:3002
pnpm dev:marketing	marketing	Public marketing site	http://localhost:3000
pnpm dev:resident	resident-portal	Resident web portal	http://localhost:3004
pnpm dev:scanner	scanner-app	Expo dev server (scanner)	Terminal QR / Expo Go
pnpm dev:mobile	resident-mobile	Expo dev server (resident)	Terminal QR / Expo Go

Custom filter (advanced): same as scripts, e.g. pnpm turbo dev --filter=client-dashboard.

Ports change if a port is already in use—always trust the terminal output.

Typical first session: one terminal with pnpm dev:client. Add pnpm dev:admin when you need platform ops UI.

Production build (all packages that define build):

pnpm build

Per-app production start scripts live in each app’s package.json (e.g. next start after next build).

8. Mobile (Expo)

1. Install Expo Go (device) or use iOS Simulator / Android Emulator.
2. Run pnpm dev:scanner or pnpm dev:mobile.
3. Open the URL or scan the QR from the CLI.

Scanner: set EXPO_PUBLIC_API_URL (e.g. http://localhost:3001/api or your LAN IP for a physical device) and EXPO_PUBLIC_QR_SECRET to match QR_SIGNING_SECRET. Configure under apps/scanner-app/.env / .env.local or inherited env; use pnpm check:env if QR or auth fails.

9. Optional: setup.sh

Legacy bash helper (may create apps/client-dashboard/.env.local). Prefer pnpm setup:dev for one root .env.local aligned with setup-dev.js.

---

🏗️ Master Architecture

GateFlow follows a modern, enterprise-grade, scalable monorepo structure powered by Turborepo and pnpm, ensuring consistent versioning and high-speed delivery paths.

/GateFlow (Root)
├── /apps                          # Mission-Critical Applications
│   ├── admin-dashboard            # Internal Platform Operations (Next.js 15)
│   ├── client-dashboard           # B2B Property Manager Portal (Next.js 15)
│   ├── marketing                  # Public Landing & SEO Funnels (Next.js 15)
│   ├── resident-mobile            # Native iOS/Android Apps (Expo 54)
│   ├── resident-portal            # Web-based Resident Utility (Next.js 15)
│   └── scanner-app               # Field Verification (React Native, Offline-First)
├── /packages                      # Shared Core Infrastructure
│   ├── db                         # Prisma + Multi-tenant middleware + Seeding
│   ├── ui                         # Atlassian Design System (ADS) Component Library
│   ├── types                      # Universal TS Types & Zod Cross-App Schemas
│   ├── i18n                       # Localized AR/EN Dictionaries
│   ├── api-client                 # Shared Type-safe Fetch Utilities
│   └── config                    # Shared ESLint + Tailwind + TSConfig Presets
└── /scripts                       # The Ralph Loop Automation Backbone

---

🛡️ Strategic Core Pillars

1. Cryptographic Access (Zero-Trust)

Verification happens exclusively on the edge. Every QR code contains a cryptographic proof of origin, ensuring gate operations continue even with zero connectivity. All sensitive field data is encrypted at rest using AES-256.

2. Physical-to-Digital Marketing ROI

The first platform to bridge the gap between digital spend and physical arrivals.

• UTM Lifecycle Persistence: Track visitors from ad-click (Meta/Google/SMS) to the physical scanner.
• Conversion APIs: Automated server-side firing to Meta Pixel and GA4 upon gate entry.

3. Atlassian Design System (ADS) Foundation

A global design token architecture ensures that brand identity, typography, and spacing are 100% consistent across web and native mobile interfaces.

---

🔒 Security & Compliance

GateFlow is built with a "Security-by-Design" philosophy.

• HMAC-SHA256 Signing: Every QR pass is cryptographically signed and immutable.
• Tenant Isolation: Prisma middleware enforces organizationId scoping on every database query.
• AES-256 Encryption: Native encryption for sensitive offline scan queues.
• RBAC Enforcement: Granular Role-Based Access Control across all dashboards.

---

🧠 Analytics & Intelligence

Transforming physical arrivals into actionable data intelligence.

• Real-time Monitoring: Server-Sent Events (SSE) push scan logs directly to administrative panels.
• GateAI Co-pilot: An agentic intelligence layer to manage infrastructure via natural language.
• Advanced Charts: High-density Recharts data visualization integrated into the "Resident CRM".

---

🌐 Localization & i18n

Engineered specifically for the Middle Eastern market.

• Arabic-First Design: Full RTL (Right-to-Left) layout support for Arabic speakers.
• Zero-Friction Switching: Clean, localized typography (Cairo font) for bi-directional support.
• Dynamic LTRS/RTL: UI components automatically adjust dimensions based on the active locale.

---

🚀 The Ralph Loop Automation

Every routine engineering task is managed by Ralph, the GateFlow autonomous engineering backbone.

• 19+ Automation Scripts: From hierarchical seeding to automated traffic emulation.
• 5 Husky Git Hooks: Enforcing committed secrets scanning, linting, and AI-tool sync.
• Phase Runner: Plan-to-dev automation with explicit gates (lint, tests, docs checks per phase).
• Type-Safe Sync: Cross-package synchronization for universal types and schemas.

---

📊 Performance & Governance

Quality is enforced in CI (lint, typecheck, tests) and optional Lighthouse workflows; dependency alignment is tracked across workspaces.

• Lighthouse initiative: Goal is consistent 100/100 where applicable; track progress in UPCOMING.md and the lighthouse.yml workflow—not a hard guarantee on every page at every commit.
• pnpm overrides: Root package.json pnpm.overrides pins shared transitive versions across workspaces.
• CI/CD: GitHub Actions for verification; web apps target Vercel, mobile via Expo EAS (see infra/README.md).

---

📚 Documentation & Support

Resource	Purpose
PRD (product reference)	Technical product specification
UPCOMING.md	Roadmap SSOT — initiatives, shipped work, strategic goals
Environment variables	Required and optional keys per app
Marketing Suite	Physical attribution and growth
Automation guide	Ralph Loop scripts and hooks
Infrastructure	Vercel, EAS, and related deployment notes
CHANGELOG	Release history
Docs index	Generated map of docs/ (run pnpm docs:index after doc moves)

---

_{Managed by the Ralph Loop Autonomous Engineering Infrastructure.
© 2026 GateFlow. All rights reserved.}