| Person | Role | Primary Focus |
|---|---|---|
| BE1 | Backend Lead | DB schema, Drizzle ORM, API routes (POI, billboard, sticker, quest, user), auth middleware, deployment |
| BE2 | Backend | Durable Object (WebSocket), content moderation, push notifications, reporting/admin API |
| FE1 | Frontend Lead | Navigation/routing, auth UI, map component, POI display, app theme/styling, admin panel |
| FE2 | Frontend | Billboard expanded view, pixel art sticker editor, sticker/sticky note placement, quest UI, profile screen, push notification handling |
-
All 4 — Whiteboard the domain model: User, POI, Billboard, Placement (Sticker/StickyNote), Quest, DailyQuest, UserProgress, Report
-
BE1 — Write
packages/db/supabase/reset.sqlwith all real tables (POIs include picture column, users include avatar + is_admin columns) -
BE1 — Write Drizzle schema in
packages/db/src/schema/(POI: picture field; User: avatar field) -
BE1 — Write shared Zod schemas in
packages/shared/src/(poi includes optional picture, user includes avatar) -
BE1 — Delete old
events-related code frompackages/shared/src/events.ts -
All 4 — Agree on sticker storage format (base64 PNG), admin role mechanism (is_admin), map provider for mobile (react-native-leaflet-view), quest system (parameterised templates), daily quest pool (~5), push timing (8–9am), billboard limits (concurrent cap + Sydney-day posting cap)
-
All 4 — Document commit practice: update PLAN.md before each commit (
CONTRIBUTING.md) -
All 4 — Pin TypeScript 5.9 across workspaces so local and CI typechecks use the same compiler
Dependency edge: Everything else depends on the shared schemas and DB schema.
- BE2 — Set up Clerk JWKS verification middleware in
apps/api/src/middleware/auth.ts - BE2 — Set up Drizzle driver + Supabase connection in
apps/api/src/db.ts - BE2 — User profile API: avatar upload (base64 PNG) +
PATCH /api/users/me/avatar - BE2 — Restructure
apps/api/src/index.ts— split into route modules (/pois,/billboards,/stickers,/quests,/users,/admin)
- FE1 — Drop
/eventsscreens, add/map,/profile,/quests,/billboard, and/createapp routes - FE1 — Integrate Clerk (
@clerk/clerk-expo) — sign-in/sign-up screens,useAuth/useUserhooks - FE1 — Build avatar drawing screen (64×64 pixel art canvas, 8-colour palette) as part of sign-up flow
- FE1 — Install Leaflet and render a basic 2D top-down map on
/map - FE1 — Set up global theme: Jersey 10 font, earthy colour palette tokens, pixel-art border styles
- FE2 — Build reusable UI components:
UsernamePill,BillboardCard,StickerGrid,LevelBadge,QuestCard,POIMarker - FE2 — Build map overlay components: POI popup, billboard marker callout/modal entry
- BE1 — POI API:
GET /api/pois(list active),GET /api/pois/:id,POST /api/pois(admin — includes optional picture field),POST /api/pois/:id/visit - BE1 — Billboard API:
GET /api/billboards,GET /api/billboards/:id,POST /api/billboards(create + moderation),DELETE /api/billboards/:id - BE1 — Sticker/Placement API:
POST /api/billboards/:id/placements,GET /api/users/me/stickers - BE2 — OpenAI Moderation API integration (
apps/api/src/services/moderation.ts) - BE2 — Quest/levelling API:
GET /api/quests,POST /api/quests/:id/claim,GET /api/users/me/progress, level-up logic
- FE1 — Map: show POI markers with distinct glowing style
- FE1 — Map: show billboard markers with note icon style
- FE1 — Map: show user's current location as their 64×64 avatar (instead of a standard dot)
- FE1 — POI discovery UX: toast when entering geofence + quest progress trigger (manual POI check-in now calls the live visit API; automatic geofence trigger still pending)
- FE2 — Billboard expanded view (~60vh overlay): text + username pill + all placements (z-ordered)
- FE2 — Pixel art sticker editor: 64×64 grid, 8-colour palette, tap-to-fill, save to collection
- FE2 — Sticky note composer: text input, preview as sticky note, post to billboard
- BE1 — Daily quest rotation logic + streak tracking
- BE1 — User profile API:
GET /api/users/:id,PATCH /api/users/me - BE2 — Durable Object: WebSocket handler, Postgres connection, broadcast on mutations
- BE2 — Expo Push Notification integration: register token, send on reply + daily reminder
- FE1 — Quest screen: main quest tiers + daily quest + streak counter + progress bars (currently backed by mock quest data)
- FE1 — Profile screen and map HUD modal: level, avatar, perks, stats, and saved stickers backed by the live user/progress API
- FE1 — Level-up celebration animation/overlay
- FE2 — WebSocket connection in app: connect to DO, listen for updates, refresh displayed data
- FE2 — Saved stickers collection picker: preserve names, browse, select, reuse stickers, and refresh quest/profile progress after saves
- FE1/FE2 — Wire quest screen to the live quest API instead of
mockQuests - FE2 — Saved sticky notes collection screen: browse, select, reuse text notes
- BE2 — Reporting API:
POST /api/reports,GET /api/admin/reports,POST /api/admin/reports/:id/action - BE2 — Analytics query endpoints: DAU, popular POIs, note volume, abuse metrics
- FE1 — Admin panel screens: reported content list with context, action buttons, soft-delete indicators, POI creation form (name, description, lat/lng, picture upload)
- FE1 — Analytics dashboard (simple stats grid)
- FE2 — Polish: error states, loading skeletons, empty states, edge cases (concurrent billboard replacement, Sydney-day posting limit, 24h inactive billboard expiry, 5-day billboard expiry, 1-placement/billboard limit)
- FE2 — Realtime refresh on map + billboard screen via WebSocket (pull-to-refresh not needed)
- FE1 — Remove stale
events/indexandevents/[id]stack declarations fromapps/app/app/_layout.tsx - FE1 — Auth page polish: tighten Clerk footer gap between "Don't have an account? Sign up" and "Secured by Clerk" branding on
sign-in.web.tsx/sign-up.web.tsx(CSS overrides inlib/clerkAppearance.ts) - FE1/BE1 — Review hardening: expose profile editing, keep POI state live, normalize avatars, redact mutation logs, and serialize saved-sticker capacity checks
Phase 0 (Domain Model)
├─► Phase 1a BE (auth middleware, route structure, DB connection)
│ └─► Phase 1b BE (POI, billboard, sticker, quest API)
│ ├─► Phase 2 FE (map markers, billboard view, editor)
│ └─► Phase 3 BE (DO WebSocket, push notifications)
│ └─► Phase 3 FE (WebSocket, quest/profile screens)
└─► Phase 1a FE (navigation, auth UI, map, theme, components)
├─► Phase 2 FE (map markers, billboard view, editor)
├─► Phase 3 FE (quest/profile screens, WS)
└─► Phase 4 FE (admin panel, polish)
Phase 1b BE ──► Phase 4 BE (reporting, analytics)
└─► Phase 4 FE (admin panel, analytics)
- Sticker storage: base64 PNG blob — FE produces B64 string, sends to BE for moderation (B64 moderation via OpenAI)
- Admin role:
is_adminboolean column onapp.users - Primary keys: internal UUIDv4 values for all primary keys; Clerk user IDs are stored as unique external auth identifiers on
app.users.clerk_user_id - Map on mobile:
react-native-leaflet-view(pavel-corsaghin/react-native-leaflet) - Drizzle migrations: Drizzle Kit with
drizzle-kit pushfor hackathon speed - Billboard limits: concurrent active cap starts at 3 and scales with level; posting at the cap soft-deletes the user's oldest active billboard before publishing the new one
- Billboard daily limit: separate Sydney calendar-day posting cap; seeded as concurrent + 1 and capped at 10/day
- Billboard expiry: derived from
empty_expires_at/expires_atin active queries (empty billboards disappear after 24 hours; all billboards disappear after 5 days) - Daily quests: seeded templates/pool; active quest is deterministically selected from the Sydney calendar day
- POI rotation: seeded/admin-created POI table; active POI set is deterministically selected from the campus calendar day
- POI geofence radius: 30m
- Quest system: parameterised templates (visit N POIs, leave N notes, place N stickers, receive N replies, save N stickers) with per-level randomised values and tier progression
- Daily quest pool: 5 curated seeded daily quests; one rotates each Sydney calendar day
- Push notification timing: 8–9am daily quest reminder when push is enabled
- POI picture: compressed 128×128 base64 PNG (stored inline in DB)
- User avatar: 64×64 pixel art drawn on sign-up, stored as base64 PNG in
users.avatar_base64column
| Property | Value |
|---|---|
| Provider | Thunderforest (Neighbourhood) |
| URL | https://api.thunderforest.com/neighbourhood/{z}/{x}/{y}{r}.png?apikey=… |
| CSS filter | sepia(0.3) saturate(0.8) brightness(0.8) contrast(150%) |
| Pixel filter | image-rendering: pixelated |
| Center | UNSW Kensington (-33.917, 151.231) |
| Default zoom | 19 on web, 18 on native |
| Max zoom | 22 (scales z21 tiles at 22 via maxNativeZoom: 21) |
components/map/
├── Map.tsx ← platform export wrapper
├── Map.web.tsx ← Leaflet ref-based wrapper (useEffect + useRef)
├── Map.native.tsx ← MapLibre native map implementation
├── markers.ts ← Leaflet divIcon factories (POI, billboard, user avatar)
├── MapHUD.tsx ← Floating bottom bar (Webfishing-style buttons)
app/
├── _layout.tsx ← ClerkProvider, QueryClientProvider, font loading, Leaflet CSS + map styles
├── index.tsx ← root redirect based on Clerk auth state
├── (auth)/
│ ├── sign-in.*.tsx
│ └── sign-up.*.tsx
└── (app)/
├── _layout.tsx ← authenticated app layout
├── map.tsx ← Map + HUD + local billboard creation/studio modals
├── quests.tsx ← quest UI currently using mock data
└── profile.tsx
Map.web.tsx — Creates Leaflet map in a useEffect ref. Adds Thunderforest Neighbourhood tiles with CSS filter injection (sepia + saturation + brightness + contrast). Renders POI markers with Leaflet popups, billboard markers that open the billboard panel flow, and the user avatar marker. Handles resize and cleanup. Avatar URL comes from the drawn profile state with an asset fallback.
Map.native.tsx — Uses @maplibre/maplibre-react-native with Thunderforest raster tiles. Renders demo POI markers, selected POI callout, and user avatar marker.
markers.ts — createPOIIcon(title), createBillboardIcon(title), and createUserAvatarIcon(imageUrl) return Leaflet L.divIcon instances for the web map.
MapHUD.tsx — Floating bottom bar (~20px from bottom, absolute positioning). Left section: profile picture (100×100), XP progress ring, and level indicator. Right section: create billboard, quests, and studio actions.
app/(app)/map.tsx — Owns the demo/local billboard state, create-billboard modal, sticker studio modal, and expanded billboard panel. Live API hooks exist for billboards/placements, but the main map screen is still using local state.
Hardcoded in constants/coordinates.ts:
- UNSW center (-33.917, 151.231)
- 5 demo POIs around campus (Main Library, Science Theatre, Quad, Roundhouse, Mathews Building)
- 1 seeded demo billboard plus locally created in-memory billboards
| Package | Version |
|---|---|
leaflet |
^1.9.4 |
@types/leaflet |
^1.9.21 |
@maplibre/maplibre-react-native |
^11.2.1 |
- POI discovery toast on geofence enter