Kidzia Kiddie Playground — Documentation

Overview

What Kidzia is, who it's for, and what it solves.

Kidzia Kiddie Playground is a full-stack management platform built for children's indoor play facilities (trampoline parks, play zones). It replaces pen-and-paper operations with a real-time digital system covering check-ins, POS sales, inventory, multi-branch analytics, and PDF reporting.

🟣 Admin Dashboard

Super admin app for managing branches, staff, pricing tiers, loyalty cards, and viewing cross-branch analytics and revenue charts.

🔵 Branch Staff App

Frontline operations app — check kids in/out, manage sessions, sell socks via POS, track stock, and export daily reports.

Key Capabilities

⏱️ Session Tracking

Real-time timers, multiple pricing tiers, loyalty discounts, and one-tap checkout.

🧦 Socks POS

Point-of-sale for sock variants with inventory adjustment and daily sales summaries.

📊 Analytics

Revenue charts, KPI cards, payment breakdowns, and multi-branch filtering.

📄 PDF Reports

Generate and share daily branch reports with full session and sales breakdown.

🔔 Notifications

Push notifications via Firebase for session timeout alerts sent to staff devices.

🏢 Multi-branch

Independent pricing, staff, and reports per branch under one admin account.

Architecture

Monorepo structure and system design.

kidzia-kiddie-playground/          ← pnpm monorepo (Turbo)
├── apps/
│   ├── admin/                     ← Super admin app (Expo, purple theme)
│   │   ├── app/(auth)/            ← login, accept-invite, unauthorized
│   │   ├── app/(tabs)/            ← dashboard, branches, employees, pricing, reports, profile
│   │   ├── components/            ← RevenueChart, MonthlyRevenueChart, VisitsChart, SecurityGate
│   │   └── stores/                ← authStore, dashboardStore, sessionsStore, ...
│   │
│   └── branch/                    ← Branch staff app (Expo, cyan theme)
│       ├── app/(auth)/            ← login, accept-invite, unauthorized
│       ├── app/(tabs)/            ← active, checkin, history, socks, stocks, reports, profile
│       ├── components/            ← SessionTimer, NotificationBanner
│       └── stores/                ← authStore, sessionsStore, socksStore, promoStore
│
├── packages/
│   └── supabase/src/              ← Shared backend client & types
│       ├── client.ts              ← Supabase client (chunked secure token storage)
│       ├── types.ts               ← TypeScript DB types for all tables
│       └── schemas.ts             ← Zod validation schemas
│
└── supabase/migrations/           ← SQL schema migrations (0001–0010)

Data Flow

Apps → packages/supabase → Supabase (PostgreSQL + Auth + Realtime). Both apps import the shared @kidzia/supabase package for all database operations, ensuring consistent types and validation across the codebase.

Layer	Technology	Purpose
Mobile / Web UI	React Native + Expo	Cross-platform apps (iOS, Android, Web)
Routing	Expo Router v6	File-based navigation with auth guards
State	Zustand	Local app state management
Backend	Supabase (PostgreSQL)	Auth, database, row-level security, realtime
Push Notifications	Firebase + Expo Notifications	Session timeout alerts to staff
Secure Storage	Expo Secure Store	JWT session persistence on device
Build	Turbo + pnpm	Monorepo task orchestration

Tech Stack

Every library and tool used across the monorepo.

📱 Frontend

React 19 React Native 0.81 Expo 54 Expo Router v6 NativeWind 4 Tailwind CSS Zustand 5 React Hook Form Zod

🗄️ Backend

Supabase PostgreSQL Supabase Auth Row-Level Security Supabase Realtime PostgreSQL Functions

🔔 Notifications & Auth

Firebase FCM Expo Notifications Expo Secure Store JWT (Supabase Auth)

🛠️ Dev & Build

TypeScript 5.7 pnpm 10 Turbo 2.3 ESLint 9 Prettier 3 Node 20+

🟣 Admin App

Super admin dashboard for system-wide management.

Bundle: com.kidzia.admin · Theme: Purple (#7c3aed)

Runs on iOS, Android, and Web via Expo. Accessible only to users with the super_admin role.

Admin Features

Multi-branch management (create, edit, deactivate)
Staff employee accounts with role assignment and branch assignment
Per-branch pricing tiers with versioned effective dates
Real-time dashboard KPIs and revenue charts
PDF report generation with custom date ranges
Loyalty card management (create, assign discount percentages)
Security mode to hide sensitive financial data on screen
Accept staff invite links for onboarding

Admin

Admin App — Tab Navigation Overview

Admin — Login

Authentication screen for super admins.

Email + password login via Supabase Auth
Accept invite link for new admin onboarding
Redirect to dashboard on successful login
Role check — non-admins are redirected to Unauthorized screen

Admin

Admin — Login Screen

Admin

Admin — Accept Invite / Set Password Screen

Admin — Dashboard

Real-time KPIs, revenue charts, and session overview.

KPI Cards

🔴 Active Sessions

Count of currently checked-in kids across selected branches.

💵 Today's Revenue

Total income today. Can be hidden via Security Mode.

📅 Yesterday's Revenue

Previous day comparison for quick trend reading.

🧾 Average Bill

Mean transaction value for the selected period.

⏱️ Avg Duration

Average play session duration in minutes.

💳 Payment Breakdown

Split by Cash, GCash, Card, Maya, Bank Transfer, Other.

Charts

📈 Monthly Revenue Trend

Month-over-month revenue comparison bar chart.

📉 Daily Visits

Daily visit count line/bar chart for trend analysis.

Admin

Admin Dashboard — KPI Cards

Admin

Admin Dashboard — Revenue & Visits Charts

Admin

Admin Dashboard — Branch Filter

Admin

Admin Dashboard — Security Mode (Hidden Metrics)

Admin — Branches

Create and manage all playground branch locations.

List all branch locations with active/inactive status
Create new branch (name, address)
Edit branch details
Soft-delete / deactivate a branch

Admin

Admin Branches — Branch List

Admin

Admin Branches — Create / Edit Branch Form

Admin — Employees

Staff account management and role assignment.

Create staff accounts with email, full name, role, and branch
Roles: super_admin or branch_staff
Assign staff to specific branches
Activate or deactivate staff accounts
Set / reset staff passwords

Staff accounts are created via a secondary Supabase client (signUpStaff()) to avoid ending the admin's current session.

Admin

Admin Employees — Staff List

Admin

Admin Employees — Create / Edit Employee Form

Admin — Pricing

Configure play session pricing tiers per branch.

Each branch has independent pricing. Pricing is versioned with effective_from dates so historical rates are preserved for reporting accuracy.

Tier	duration_minutes	Notes
30 minutes	`30`	Short play tier
1 hour	`60`	Standard tier
2 hours	`120`	Extended play
Unlimited	`NULL`	Full day / open-ended pass

Admin

Admin Pricing — Pricing Tiers List

Admin

Admin Pricing — Add / Edit Pricing Tier Form

Admin — Reports

Generate and export PDF reports for any custom date range.

Custom date range selection via calendar picker
Session breakdown: check-in/out times, duration, revenue, discounts
Sock sales summary per variant
Staff on duty listing
Payment method breakdown
PDF export via Expo Print API and system share sheet

Admin

Admin Reports — Date Range Picker

Admin

Admin Reports — Report Preview / PDF Output

🔵 Branch App

Frontline operations app for branch staff.

Bundle: com.kidzia.branch · Theme: Cyan (#0ea5e9)

Runs on iOS, Android, and Web. Accessible only to branch_staff role. Includes Firebase push notification support.

Branch Staff Features

Check kids in with full info (name, age, parent, emergency contact)
Real-time session timer with visual countdown per kid
Multiple pricing tiers + promo pricing (50% off, PWD discounts)
Loyalty card scanning with automatic discount calculation
Extend session duration mid-play
Revert checkout — undo accidental checkouts with full audit log
Socks point-of-sale with shopping cart and payment selection
Inventory tracking with receive / manual set / correction adjustments
Daily report generation and PDF sharing
Push notifications for session timeouts

Branch — Login

Authentication screen for branch staff.

Email + password login via Supabase Auth
Accept invite link for new staff onboarding
Redirects to active sessions on successful login
Non-staff roles redirected to unauthorized page

Branch

Branch — Login Screen

Branch — Active Sessions

Live view of all currently checked-in kids with timers and quick actions.

Action	Description
⏱️ Live Timer	Real-time countdown per session based on the purchased tier duration
➕ Extend	Add more time by selecting a new duration tier mid-session
✅ Check Out	Opens checkout form — scan loyalty card, pick payment method, confirm total
↩️ Revert	Undo a completed checkout — restores session to active with full audit log

Branch

Active Sessions — Session List with Live Timers

Branch

Active Sessions — Checkout Form

Branch

Active Sessions — Extend Session

Branch

Active Sessions — Revert Checkout Confirmation

Branch — Check-in

Register a new kid and start their play session.

Field	Required	Notes
Kid Name	✅ Yes	Auto-fills from previous sessions
Kid Age	✅ Yes	Numeric input
Parent Name	✅ Yes
Parent Contact	✅ Yes	Phone number
Emergency Contact	Optional	Alternative contact person
Notes	Optional	Special requests or conditions
Pricing Tier	✅ Yes	30 min / 1 hr / 2 hrs / Unlimited
Promo Type	Optional	Regular / 50% Off / PWD / 50%+PWD

Branch

Check-in — Kid & Parent Info Form

Branch

Check-in — Pricing Tier & Promo Selection

Branch — History

Today's completed sessions log.

All checked-out sessions for the current day
Session details: kid name, check-in/out times, duration, total revenue
Payment method and discounts visible per entry

Branch

History — Completed Sessions List

Branch — Socks POS

Point-of-sale for sock merchandise with shopping cart.

Sock Variants (₱20 each)

Baby Boys Baby Girls Kids Boys Kids Girls Adult Men Adult Women

Add variants to shopping cart with quantity adjustment
Remove items from cart
Select payment method (Cash, GCash, Card, Maya, etc.)
Submit sale — deducts from stock automatically
Daily sales summary with per-variant breakdown
Revenue tracked per payment method

Branch

Socks POS — Product Selection & Cart

Branch

Socks POS — Daily Sales Summary

Branch — Stocks

Real-time sock inventory management and adjustment tracking.

Adjustment Type	Description
`receive`	New stock received from supplier
`manual_set`	Manual count override (physical stock count)
`sale`	Auto-deducted when a POS transaction is completed
`correction`	Error correction adjustments

Real-time stock levels per variant
Low stock alert visual indicator (threshold: <10 units)
Stock adjustment form with type and optional notes
Full adjustment history log with timestamps and staff attribution

Branch

Stocks — Inventory Levels Per Variant

Branch

Stocks — Low Stock Alert

Branch

Stocks — Stock Adjustment Form

Branch

Stocks — Adjustment History Log

Branch — Reports

Comprehensive daily report with PDF export and sharing.

Full daily session list with check-in/out times and duration
Sock sales transactions breakdown per variant
Staff on duty for the day
Payment method totals (Cash, GCash, Card, Maya, etc.)
Total revenue and total discounts applied
Export via system share sheet using Expo Print + Share APIs

Branch

Branch Reports — Daily Report Summary Screen

Branch

Branch Reports — PDF Export / Share Sheet

Database Schema

All PostgreSQL tables managed via Supabase.

🗄️

Supabase — Database Tables Overview

Click to upload a screenshot of the Supabase dashboard showing all tables

DB

🏢 branches

iduuid PKAuto-generated primary key

nametextBranch display name

addresstextPhysical address

is_activebooleanSoft-delete flag

created_attimestamptzCreation timestamp

👤 profiles

iduuid PK FKReferences auth.users

full_nametextDisplay name

roleenumsuper_admin | branch_staff

branch_iduuid FK?Assigned branch (null for super_admin)

is_activebooleanAccount active flag

🎫 sessions

iduuid PK

branch_iduuid FKBranch where session occurred

kid_nametextChild's name

kid_ageintegerChild's age in years

parent_nametextParent/guardian name

parent_contacttextPhone number

check_in_attimestamptzSession start time

check_out_attimestamptz?Session end time (null if active)

duration_minutesinteger?Purchased tier (null = unlimited)

rate_per_hournumericRate at time of check-in

base_amountnumericAmount before discounts

loyalty_card_iduuid FK?Applied loyalty card

discount_amountnumericAmount discounted

total_amountnumericFinal amount charged

payment_statusenumpending | paid

expo_push_tokentext?Device token for timeout notifications

checked_in_byuuid FKStaff who checked in

checked_out_byuuid FK?Staff who checked out

💳 loyalty_cards

iduuid PK

card_numbertext UNIQUEUnique card identifier for scanning

holder_nametextCard holder's name

discount_percentageintegerDiscount 0–100%

is_activebooleanCard active flag

💰 pricing_configs

iduuid PK

branch_iduuid FKBranch this pricing belongs to

duration_minutesinteger?NULL = unlimited tier

rate_per_hournumericPrice for this tier

effective_fromdateVersioned pricing start date

🧦 Socks Tables (sock_variants, sock_stock, sock_sales, sock_sale_items, sock_stock_adjustments, sock_daily_summaries)

sock_variantstable6 pre-seeded variants: Baby/Kids/Adult × Boys/Girls, ₱20 each

sock_stocktableCurrent stock quantity per branch per variant

sock_salestablePOS transaction header (total, payment method, sold_at, sold_by)

sock_sale_itemstableLine items per sale (variant, qty, unit_price, subtotal)

sock_stock_adjustmentstableFull log of all stock changes (type, qty_before, qty_change, qty_after, note)

sock_daily_summariestableDaily summary with variant_breakdown and payment_breakdown as JSONB

📋 branch_daily_reports

branch_id + report_datecompositeOne report per branch per day

total_sessionsintegerNumber of play sessions

checkin_revenuenumericRevenue from play sessions

total_discountsnumericTotal discounts applied

socks_revenuenumericRevenue from sock sales

total_revenuenumericcheckin_revenue + socks_revenue

staff_on_dutyjsonb[]Array of staff who worked that day

session_breakdownjsonbFull session list with details

payment_breakdownjsonbTotals per payment method

↩️ checkout_revert_log

session_iduuid FKSession that was reverted

reverted_byuuid FKStaff who performed the revert

original_checkout_attimestamptzTimestamp of the reverted checkout

original_total_amountnumericAmount from the reverted checkout

reverted_attimestamptzWhen the revert was performed

notestext?Reason for reversion

Database Migrations

Incremental SQL migrations in supabase/migrations/.

0001 — Initial Schema

Core tables: branches, profiles, pricing_configs, loyalty_cards, sessions

0002 — Pricing Duration Tiers

Adds duration_minutes to pricing_configs for tiered pricing

0003 — Push Notifications

Adds expo_push_token and end_time fields to sessions

0004 — Payment Methods & Fixed Price

Adds payment_method enum, refactors pricing model

0005 — Drop Old Checkout Overload

Cleans up deprecated checkout_session function overload

0006 — Socks POS

Adds sock_variants, sock_stock, sock_sales, sock_sale_items, sock_daily_summaries

0007 — Stock Adjustments

Adds sock_stock_adjustments table for full inventory audit trail

0008 — Branch Daily Reports

Adds branch_daily_reports table for consolidated end-of-day reporting

0009 — Revert Checkout

Adds checkout_revert_log and revert_checkout() PostgreSQL function

0010 — Revert Checkout (No Window)

Refines revert_checkout() — removes time-window restrictions on reverts

Database Functions

PostgreSQL stored functions for complex atomic operations.

⚡ checkout_session()

checkout_session(
  p_session_id       uuid,
  p_loyalty_card_num text?,
  p_checked_out_by   uuid?
)
→ { success: bool, message: text, total_amount: numeric }

Calculates actual play duration, looks up loyalty card discount, marks payment_status as 'paid', and returns the final charged amount. Executes atomically in a single DB call.

⚡ get_current_rate()

get_current_rate(p_branch_id uuid)
→ numeric   -- current rate_per_hour for the branch

Returns the most recent active pricing rate for a branch based on effective_from date.

⚡ revert_checkout()

revert_checkout(
  p_session_id  uuid,
  p_reverted_by uuid
)
→ { success: bool, message: text }

Reverts a completed checkout — clears check_out_at, resets all payment fields back to pending, and writes a full audit entry to checkout_revert_log. No time-window restriction.

Auth & Security

Role-based access control, RLS policies, and session persistence.

🔑 Authentication

Supabase Auth with email/password. JWTs are persisted in expo-secure-store using a chunked adapter to work around the 2KB per-key limit.

🛡️ Row-Level Security

All tables have RLS enabled. Branch staff can only access data for their own branch. Super admins have broader cross-branch access.

👮 Role Guards

Both apps read the user's role from the profiles table after login and redirect unauthorized roles to a dedicated Unauthorized screen.

🔒 Staff Creation

Admin uses a secondary Supabase client (signUpStaff()) to create staff accounts without ending the current admin session.

User Roles

Role	App Access	Capabilities
`super_admin`	Admin App only	All branches, employees, pricing, cross-branch analytics, custom date range reports
`branch_staff`	Branch App only	Check in/out kids, sell socks, manage stock, generate daily branch report for their branch

Push Notifications

Firebase-powered push alerts for session timeouts.

Expo push token captured at check-in and stored in the session row
Notifications triggered when a session timer is about to expire
Foreground notification handler always shows alert banners in-app
Tapping a notification navigates directly to the Active Sessions tab
Firebase Cloud Messaging (FCM) delivery via google-services.json
Expo Notifications API for cross-platform (iOS + Android) delivery

Push tokens are stored per-session (not per-user), allowing notifications to target the specific device that checked in a particular child.

🎪 Kidzia Kiddie Playground

Overview

Key Capabilities

Architecture

Data Flow

Tech Stack

🟣 Admin App

Admin Features

Admin — Login

Admin — Dashboard

KPI Cards

Charts

Admin — Branches

Admin — Employees

Admin — Pricing

Admin — Reports

🔵 Branch App

Branch Staff Features

Branch — Login

Branch — Active Sessions

Branch — Check-in

Branch — History

Branch — Socks POS

Sock Variants (₱20 each)

Branch — Stocks

Branch — Reports

Database Schema

Database Migrations

Database Functions

Auth & Security

User Roles

Push Notifications