Implementation Tasks

Ordered task breakdown for building the 1 OAK MLS Platform.

Phase 1: Foundation

Task 1.1: Project Setup

• Initialize monorepo structure (apps/admin, apps/web, packages/*)
• Set up Next.js 14 with App Router for admin app
• Configure TypeScript strict mode
• Set up Tailwind CSS
• Configure ESLint + Prettier
• Create .env.example with all required variables

Deliverable: Empty Next.js app that builds and runs

Task 1.2: Supabase Setup

• Create Supabase project (or use existing)
• Enable required extensions (pgcrypto)
• Set up local development with Supabase CLI

Deliverable: Supabase project with local dev environment

Task 1.3: Database Migrations

• Create migration: 001_extensions.sql (pgcrypto)
• Create migration: 002_workspaces.sql (workspaces, workspace_domains)
• Create migration: 003_mls_connections.sql
• Create migration: 004_field_mappings.sql
• Create migration: 005_listings.sql (listings + indexes)
• Create migration: 006_listing_media.sql
• Create migration: 007_user_profiles.sql
• Create migration: 008_favorites_saved_searches.sql
• Create migration: 009_compliance_profiles.sql
• Create migration: 010_sync_runs.sql
• Create migration: 011_rls_policies.sql
• Run migrations against local and production

Deliverable: Full schema deployed to Supabase

Task 1.4: Type Generation

• Generate TypeScript types from Supabase schema
• Create shared types package (packages/shared)
• Export Database type for Supabase client
• Create canonical types (Listing, Workspace, etc.)

Deliverable: Type-safe database access

Phase 2: Sync Engine

Task 2.1: Bridge API Client

• Create packages/sync package
• Implement Bridge API client class
• Add authentication handling
• Implement OData query builder
• Add pagination support (follow nextLink)
• Add retry logic with exponential backoff
• Write tests with mock responses

Deliverable: Working Bridge API client

Task 2.2: Token Encryption

• Implement AES-256-GCM encryption helpers
• Create encrypt/decrypt functions
• Add KEY rotation support (future)
• Test encryption round-trip

Deliverable: Secure token storage

Task 2.3: Field Mapping Engine

• Create mapping transformer function
• Handle missing/null fields gracefully
• Preserve raw payload in raw column
• Add validation function (check required fields)
• Test with sample Bridge responses

Deliverable: RESO → canonical transformation

Task 2.4: Postgres Sync Functions

• Implement upsertListings() (batch upsert)
• Implement upsertMedia() (per listing)
• Implement sync run logging
• Implement checkpoint updates
• Handle conflicts correctly (ON CONFLICT)

Deliverable: Reliable database sync

Task 2.5: Typesense Setup

• Create packages/typesense package
• Implement collection creation function
• Implement document transform (DB → Typesense)
• Implement batch indexing (40 docs/batch)
• Implement collection delete/rebuild
• Test with local Typesense instance

Deliverable: Typesense indexing pipeline

Task 2.6: Full Sync Worker

• Implement runFullSync() function
• Wire up: fetch → transform → upsert → index
• Add progress logging
• Handle errors and write to sync_runs
• Test with real Bridge data (test dataset)

Deliverable: Working full sync

Task 2.7: Incremental Sync Worker

• Implement runIncrementalSync() function
• Build ModificationTimestamp filter
• Use last_synced_at checkpoint
• Handle "no changes" case
• Test incremental updates

Deliverable: Working incremental sync

Task 2.8: Sync API Endpoints

• Create /api/admin/workspaces/[id]/sync/run endpoint
• Add authorization check
• Support mode parameter (full/incremental)
• Return sync run ID
• Create /api/cron/sync for scheduled runs

Deliverable: Sync triggerable via API

Phase 3: Admin UI

Task 3.1: Admin Layout & Auth

• Create admin layout with sidebar
• Implement Supabase Auth for admin
• Create login page
• Add middleware for route protection
• Implement role check (admin only)

Deliverable: Protected admin shell

Task 3.2: Workspace List Page

• Create /admin/workspaces page
• Build workspace table/grid
• Show status, domains, listing counts
• Add quick actions (pause/resume)
• Implement search/filter

Deliverable: Workspace management home

Task 3.3: Create Workspace Flow

• Create /admin/workspaces/new page
• Build workspace form
• Auto-generate slug from name
• Create workspace + defaults on submit
• Redirect to MLS config

Deliverable: Workspace creation

Task 3.4: Workspace Overview

• Create /admin/workspaces/[id]/overview page
• Show stats cards (listing counts)
• Show last sync status
• Show domains list
• Add quick action links

Deliverable: Workspace dashboard

Task 3.5: MLS Connection Config

• Create /admin/workspaces/[id]/mls page
• Build connection form
• Implement "Test Connection" action
• Mask token display
• Save encrypted token

Deliverable: MLS configuration

Task 3.6: Field Mapping Editor

• Create /admin/workspaces/[id]/mapping page
• Integrate JSON editor (Monaco or similar)
• Implement validation endpoint
• Show field mapping status
• Save new versions

Deliverable: Mapping management

Task 3.7: Sync Monitor

• Create /admin/workspaces/[id]/sync page
• Build sync runs table
• Add "Run Sync" buttons
• Show live status when running
• Display error details

Deliverable: Sync monitoring

Task 3.8: Compliance Config

• Create /admin/workspaces/[id]/compliance page
• Build HTML editor for attribution/disclaimer
• Add preview rendering
• Toggle display settings
• Save to compliance_profiles

Deliverable: Compliance management

Phase 4: Client Site

Task 4.1: Client Site Setup

• Create apps/web Next.js app
• Configure for multi-tenant (middleware workspace detection)
• Set up Tailwind with custom theme
• Create shared layout

Deliverable: Client site shell

Task 4.2: Search Page

• Create /search page
• Build Typesense search integration
• Implement faceted filters UI
• Add sort dropdown
• Build listing grid/cards
• Add pagination
• Show compliance text

Deliverable: Working search experience

Task 4.3: Listing Detail Page

• Create /listings/[id] page
• Fetch listing from Postgres (SSR)
• Display all property details
• Photo gallery component
• Show compliance text
• Add contact CTA

Deliverable: Listing detail view

Task 4.4: Static Pages

• Create Home page with search entry
• Create About page
• Create Contact page (form)
• Style to match workspace branding

Deliverable: Complete client site

Phase 5: User Features

Task 5.1: User Authentication

• Add Supabase Auth to client site
• Create sign up / sign in pages
• Create user profile on sign up
• Add auth state to layout

Deliverable: User authentication

Task 5.2: Favorites

• Add favorite button to listing card
• Implement add/remove favorite API
• Create favorites page
• Sync favorite state in search results

Deliverable: Save favorites feature

Task 5.3: Saved Searches

• Add "Save Search" button to search page
• Create saved searches page
• Implement re-run saved search
• (Future) Email alerts for new matches

Deliverable: Saved searches feature

Phase 6: Production Readiness

Task 6.1: Environment Configuration

• Set up production env vars
• Configure Vercel project(s)
• Set up Typesense Cloud (or self-hosted)
• Configure domains

Deliverable: Production infrastructure

Task 6.2: First Workspace: Lainey Levin

• Create workspace in production
• Configure Bridge connection (Miami Realtors)
• Set up field mapping
• Run initial full sync
• Verify search works
• Configure compliance text
• Connect domain

Deliverable: Live first client

Task 6.3: Monitoring & Alerts

• Add error tracking (Sentry)
• Set up sync failure alerts
• Add uptime monitoring
• Create runbook for common issues

Deliverable: Production monitoring

Task 6.4: Documentation

• Write onboarding guide for new workspaces
• Document Bridge setup process
• Create troubleshooting guide
• Document API endpoints

Deliverable: Operational docs

Stretch Goals (V2)

• Map-based search with clustering
• SEO-friendly URLs (/miami-beach/condos/[slug])
• Photo caching/CDN proxy
• Email alerts for saved searches
• Agent dashboard
• Lead capture and routing
• Multiple MLS providers
• Cross-workspace search (admin)

Suggested Sprint Plan

Critical Path

The minimum viable product requires:

1. Database schema deployed
2. Sync engine working (full + incremental)
3. Typesense indexing working
4. Admin: create workspace + MLS config + trigger sync
5. Client: search page + listing detail
6. Compliance text displayed

Everything else enhances but doesn't block launch.