1. Executive Summary

The City of Daytona Beach is commissioning the development of a comprehensive digital platform that integrates a cross-platform mobile application, a web-based administration portal, and a unified Supabase backend. This initiative is designed to enhance civic engagement, streamline access to public information, and modernize the delivery of city services through mobile, web, and emerging immersive technologies.

The scope covers:

• React Native mobile app deployed with Expo EAS, targeting both iOS and Android.

• Web Administration Portal built in Next.js or Nuxt, hosted on Vercel with CI/CD pipelines linked to GitHub.

• Supabase backend for authentication, data storage, file handling, and real-time synchronization.

• AI Assistant (“Ask Daytona”) integrating OpenAI GPT for context-aware responses limited to city-owned data.

• GIS & AR/VR modules leveraging ArcGIS and Agents of Discovery APIs for interactive park and facility experiences.

• Notification System using Resend (email), Twilio (SMS), and Expo Notifications (push) with full subscription management.

This specification defines the technical architecture, security standards, testing requirements, and delivery milestones necessary for a successful deployment. It merges contractual clarity with deep engineering detail to ensure alignment between the City, development contractors, and internal IT staff.

2. Ownership & Governance

All intellectual property, source code, databases, designs, and digital assets produced under this contract are the exclusive property of the City of Daytona Beach. No third-party vendor, subcontractor, or developer retains ownership or licensing rights to any portion of the final system.

Account Control

All environments will be provisioned in City-owned accounts, including but not limited to:

• Apple Developer Program

• Google Play Console

• Expo.dev (organization workspace)

• GitHub (private repositories)

• Supabase (project instances & storage buckets)

• Vercel (hosting for Admin Portal)

• Resend (email delivery)

• Twilio (A2P SMS & voice services)

• ArcGIS (Esri Developer Account)

• Agents of Discovery (Mission API Access)

• Microsoft Graph API integration for SharePoint data exchange

Governance Framework

• Project Steering Committee: Comprised of City IT, Communications, and Procurement divisions. Approves requirements, milestones, and deliverables.

• Change Management: All scope changes must be submitted as formal change requests with impact analysis on budget and timeline.

• Source Control: All repositories reside under the City’s GitHub organization. Pull requests require review and approval from City-designated maintainers.

• Code Ownership: Every line committed to City repos is licensed to the City under permanent exclusive rights. Developers are prohibited from reusing proprietary components outside this project.

• Audit & Access: City administrators retain the right to review logs, deployment pipelines, and cloud configurations at any time.

Deliverable Transfer Protocol

At project completion, the developer must:

1. Transfer ownership of all accounts, tokens, and certificates to the City’s IT department.

2. Commit final source code to City-owned repositories with documentation and version tags.

3. Deliver a complete asset package (Figma files, source images, icons, fonts, and documentation).

4. Provide credential handover and revocation confirmation.

3. Project Components

The Daytona Beach Civic Engagement Platform consists of three major components and a set of interconnected subsystems. Together, they form a unified architecture designed for scalability, performance, and maintainability.

3.1 Mobile Application (React Native + Expo EAS)

The mobile app delivers civic information, city services, and interactive experiences for residents, visitors, and city staff.

• Framework: React Native (Expo SDK 51+), TypeScript-enabled for type safety.

• Distribution: iOS (App Store) and Android (Play Store) via Expo Application Services

(EAS).

• Offline-first: Core data cached locally with synchronization on reconnect.

• Authentication: Supabase Auth supporting email/password and optional Microsoft login.

• Data Integration: Real-time Supabase subscriptions and REST endpoints for live updates.

• Modules:

o City Highlights (news, alerts, events) o Events Calendar with RSVP and Add-to-Calendar o Parks & Recreation (with AR/VR experiences) o City Services (directory + quick links) o AI Chat Assistant (“Ask Daytona”) o Dynamic Pages under More tab (fetched from Supabase tables) o Push Notifications (Expo SDK integrated)

Device Compatibility:

• iOS: 14.0 and later (optimized for SE → iPhone 15 Pro Max)

• Android: API 24+ (Nougat and above)

3.2 Web Administration Portal (Next.js or Nuxt + Vercel)

A responsive, secure content management portal for internal staff.

• Hosting: Vercel under the City’s organizational account.

• Authentication: Supabase Auth with role-based permissions (Admin, Editor, Viewer).

• Primary Functions:

o Manage city highlights, events, and dynamic pages.

o Upload photos, documents, and video content to Supabase Storage.

o Compose and schedule push, SMS, and email notifications.

o Configure external WebView links for the mobile app.

o Manage subscriptions, AI knowledge base, and site settings.

• UI Framework: TailwindCSS + City Design Tokens from Figma.

• CI/CD: Auto-deployment on commit to main via GitHub Actions + Vercel integration.

3.3 Supabase Backend (Postgres + Edge Functions)

Supabase acts as the unified data backbone.

• Database: PostgreSQL with Row-Level Security (RLS).

• Auth: Email/password, OAuth (optional), JWT-based sessions.

• Storage: Buckets for images, videos, and documents.

• Realtime: WebSocket updates for live event feeds and chat.

• Edge Functions:

o Notification dispatch (Resend, Twilio, Expo) o AI query pre-processing o SharePoint → Supabase sync o Email confirmations and subscription updates o Analytics aggregation for the admin dashboard

• Performance: PostgREST API auto-generated endpoints with caching enabled.

3.4 AI Assistant (“Ask Daytona”)

• Engine: OpenAI GPT-4 (or current stable model).

• Scope: Limited to City of Daytona Beach content only (no open internet access).

• Knowledge Base:

o Data from DaytonaBeach.gov (scraped via controlled crawler).

o City-managed Supabase tables (pages, news, staff directory).

• Functionality:

o Conversational interface with voice input/output.

o Citations to data sources for every response.

o Offline fallback with pre-stored FAQs.

• Privacy: No PII stored in chat history; optional local-only storage per user session.

3.5 Notifications & Communications System

• Email: Resend (transactional + subscription alerts).

• SMS: Twilio (A2P 10DLC registered).

• Push: Expo Notifications.

• Preference Management:

o Users toggle per-channel preferences in the app.

o Stored in Supabase subscriptions and profiles tables.

o Edge Functions handle email verification, STOP/START/HELP compliance, and rate limits.

• Message Templates: Stored in Supabase with variables {first_name}, {event_time}, {cta_link}.

3.6 Third-Party Integrations (WebView Modules)

The mobile app integrates with existing city and partner systems via in-app WebViews.

Each link opens inside the app with navigation controls, offline fallback, and share options.

Examples:

• SeeClickFix (Report Concerns)

• CivicWeb (Agendas & Minutes)

• Utility Services Portal (Billing)

• Recreation Catalog (Rec1)

• Public Records (JustFOIA)

• Land Management System (IMS16)

• and others listed in Appendix D.

All WebViews inherit the city’s theme colors and include navigation and error handling overlays.

4. Data Model & Backend Architecture

Supabase serves as the single source of truth for data flowing between SharePoint, the Admin Portal, and the Mobile App.

All tables enforce Row-Level Security (RLS) and maintain automatic timestamps.

Each service (Resend, Twilio, Expo, OpenAI, ArcGIS) interacts through Edge Functions or authenticated REST calls.

4.1 Core Schema

Table Purpose Key Fields profiles user identity and contact prefs id uuid pk, email, phone_e164, role, email_verified_at, sms_verified_at posts city highlights / blog entries id uuid, title, excerpt, body_html, category, published_at, author_id events calendar data synced from SharePoint id uuid, title, start_time, end_time, location, category, image_url, rsvp_url pages dynamic pages for “More” tab id, slug, title, status, schedule_at, updated_at content_blocks page elements (text, image, video, form) id, page_id, type, content_json, order_index staff staff directory id, name, title, department_id, email, phone, photo_url departments staff hierarchy id, name, color_hex subscriptions user preferences per list profile_id, list_id, email_enabled, sms_enabled, push_enabled subscription_lists definitions of topics id, key, description, default_email, default_sms, priority notification_events messages queued for dispatch id, list_id, title, body_markdown, scheduled_at notification_dispatches per-user delivery log event_id, profile_id, channel, status, sent_at gis_locations coordinates for parks, buildings id, name, lat, lng, category, amenities

Table Purpose Key Fields kb_documents scraped city content for

AI

id, url, title, text_content, last_crawled kb_chunks vectorized embeddings for search id, document_id, embedding vector(1536), content, metadata

4.2 Storage Buckets

public/images → Event & staff photos public/videos → DBTV archives & VR assets public/documents → PDFs and uploaded forms private/user-uploads → Citizen submissions (RLS restricted)

Each file carries a signed URL with expiry tokens managed through Edge Functions.

4.3 Edge Functions

/notify/dispatch Handles queued notifications across email (Resend), SMS (Twilio), and push (Expo).

Includes retry logic and idempotency keys.

/sync/sharepoint Fetches Lists from Microsoft Graph API → normalizes → writes to Supabase tables.

/ai/search Retrieves embeddings from kb_chunks, performs vector similarity + text filter, returns structured context to OpenAI API.

/forms/submit Validates and routes incoming forms; uploads attachments to Supabase Storage and sends email confirmation via Resend.

/analytics/report Aggregates daily events (page views, downloads, notifications sent) for Admin dashboard visualizations.

4.4 Data Flow

1. City Staff Input → SharePoint Lists

2. Automated Sync → Supabase via Graph API

3. Realtime Replication → Mobile App and Admin Portal

4. Edge Functions → Notifications, Search, Forms

5. Cached Offline in SQLite/AsyncStorage

6. User Interaction → Data Updates → Supabase via Auth Session

4.5 Offline and Sync Strategy

• Expo SQLite: Structured caching (events, posts, staff).

• AsyncStorage: Simple key-value (user prefs, theme, session).

• SecureStore: Sensitive tokens (auth, push ID).

• Background Sync: Triggered when network returns; reconciles via timestamp diff.

• Conflict Resolution: “Last write wins” for non-critical data; manual merge for forms.

• Visual Indicator: Offline badge and manual refresh option in UI.

4.6 Performance Targets

• App launch: ≤ 3 s on mid-range device

• API response: ≤ 2 s 95th percentile

• Realtime latency: ≤ 500 ms for event pushes

• Offline cache sync: ≤ 10 s post-reconnect

• Battery impact: ≤ 3 % per hour average use

4.7 Security Implementation

• Row-Level Security on every table with JWT claims.

• Edge Functions authenticated via service role keys.

• All external API calls use server-side proxies to hide credentials.

• Supabase storage signing with 10-minute expiry URLs.

• Logs redact email, phone, address before storage.

5. AI Assistant Architecture (“Ask Daytona”)

5.1 Objective

Deliver an AI assistant that answers resident questions about city services, staff, events, and facilities with contextual accuracy. The system must only use City-authorized data (no external open web queries) and be auditable for accuracy and bias.

5.2 Knowledge Base Composition

Data Sources:

1. City of Daytona Beach official website (daytonabeach.gov)

2. Supabase tables:

o posts (news, highlights) o events (calendar data) o pages (dynamic content) o staff (directory) o gis_locations (facilities and parks)

3. Static municipal datasets (FAQs, emergency procedures)

4. Admin-curated documents (policy PDFs, press releases)

Ingestion Process:

• Nightly crawler runs Edge Function /ai/crawl.

• HTML and SharePoint content are sanitized and converted to plain text.

• Metadata (source URL, title, category) stored in kb_documents.

• Each document segmented into ≤1000 token chunks stored in kb_chunks.

• Chunks vectorized using text-embedding-3-large and indexed in Supabase pgvector.

• Language field (en, es, fr) included for multilingual support.

5.3 Query Flow

1. User input: Text or voice → transcribed locally (Expo Speech API).

2. Edge Function /ai/search:

o Embeds query vector.

o Performs hybrid search: cosine similarity on vectors + full-text match on tsvector.

o Returns top 10 matches with metadata.

3. Context construction:

o Combines chunks into 2,000-token prompt context.

o Appends system guardrails (“respond only with City of Daytona Beach data”).

4. OpenAI call:

o Model: gpt-4-turbo or higher.

o Temperature: 0.3 (low randomness).

o Max tokens: 800 output.

5. Response:

o Returns structured JSON with answer, citations, confidence_score, and sources.

o Displayed in conversational UI with message bubbles and optional text-to-speech playback.

5.4 Offline Behavior

• Pre-loads a mini knowledge set (faqs.json) covering basic topics: hours, utility contacts, event calendar summary.

• Returns canned responses when offline, labeled “Offline Mode.”

5.5 Privacy & Security Controls

Concern Mitigation

Data leakage No external corpus; URLs whitelisted.

Logging Inputs and outputs truncated and anonymized.

PII Names/emails stripped before embedding.

Retention Vector data retained; raw text pruned every 30 days.

Review Admin portal audit tool shows source and response pairs.

Compliance: All AI functionality conforms to City privacy policy and federal Section 508 accessibility requirements.

5.6 Admin Portal – AI Management

In the Admin web app:

• Dashboard shows last crawl date and document count.

• Controls to pause ingestion or re-index data.

• Diff viewer shows text changes since last crawl.

• Button to exclude pages from AI training.

• Regeneration of embeddings triggered on demand.

5.7 Performance Metrics

• Query latency ≤ 3 seconds end-to-end.

• Accuracy target ≥ 85% answer precision on internal QA set.

• 99% uptime for Edge Function /ai/search.

• Crawl process under 15 minutes nightly for ≤10k pages.

5.8 Future Enhancements (Optional)

• Voice Assistant mode (device microphone + text-to-speech).

• Contextual handoff to City staff (link to form or chat agent).

• Topic trend dashboard from anonymized logs.

6. Notifications & Communication System Architecture

6.1 Objective

Provide a unified system that delivers email, SMS, and push notifications to residents, staff, and subscribers.

Each channel must be preference-aware, traceable, and compliant with both TCPA (for SMS) and CAN-SPAM (for email).

6.2 Channels & Providers

Channel Provider Purpose

Email Resend Transactional + subscription communications

SMS Twilio A2P 10DLC Critical alerts + reminders

Push Expo Notifications App-based alerts + event updates

All messages originate from Edge Function /notify/dispatch, which selects the proper provider per user preference.

6.3 Supabase Schema for Notifications

Table Description subscription_lists Definitions of topics (e.g., Emergency Alerts, City News).

subscriptions User preferences per topic and channel.

notification_events Outbound messages (queued or scheduled).

notification_dispatches Per-user log of actual delivery attempts.

Each dispatch record includes status, attempts, and error fields for retry tracking.

6.4 Notification Flow

1. Trigger Event – Manual (admin compose) or automated (system event).

2. Audience Selection – Query subscriptions where channel enabled = true.

3. Queue Creation – Insert rows into notification_dispatches.

4. Delivery Handler /notify/dispatch executes:

o sendEmail() via Resend API.

o sendSMS() via Twilio Messaging Service SID.

o sendPush() via Expo token endpoint.

5. Retry Logic – 3 attempts with exponential backoff (1 min → 5 min → 15 min).

6. Status Update – Mark sent, failed, or skipped.

7. Metrics Aggregation – Edge Function writes daily counts for analytics.

6.5 Preference Management

Residents manage notifications in the mobile app under Settings → Notifications.

Action Result

Toggle a topic off Sets email_enabled/sms_enabled/push_enabled = false in subscriptions.

Unsubscribe from email link

Redirects to hosted preference page (updates Supabase).

Text “STOP” to SMS Twilio webhook updates record → sms_enabled = false.

App reinstall Expo token re-registered and re-linked to profile_id.

6.6 Compliance & Governance

• Email Deliverability: City domain authenticated via SPF/DKIM/DMARC.

• SMS A2P 10DLC: Brand and campaign registered; STOP/START/HELP keywords enabled.

• Privacy: No PII in message bodies; links use short first-party domain.

• Audit Log: All dispatch attempts recorded for 90 days.

• Quiet Hours: Non-critical topics muted 10 p.m.–7 a.m. local time.

6.7 Edge Function Pseudocode (plain text)

for recipient in audience:

key = f"{event_id}:{recipient_id}:{channel}" if alreadySent(key): continue try:

payload = renderTemplate(event, recipient) provider.send(payload) markSent(key) except Exception as e:

logFailure(key, str(e))

6.8 Message Templates

Templates are editable from the Admin Portal.

Each supports placeholders for merge fields (e.g., {first_name}, {event_time}, {cta_link}) and are versioned for rollback.

6.9 Analytics & Reporting

• Open and click tracking for Resend emails.

• Delivery success rate metrics by channel.

• Admin dashboard shows weekly volume and error trend.

• Alerts triggered if success rate < 95 % or latency > 5 minutes.

7. GIS, Mapping & AR/VR Subsystem Design

7.1 Objective

Integrate a geospatial experience across parks, facilities, and landmarks, and enrich it with immersive AR/VR functionality.

This allows residents and visitors to explore Daytona Beach interactively—via map markers, virtual tours, and augmented navigation.

7.2 Mapping Stack

Framework: react-native-maps (Google Maps SDK on Android, MapKit on iOS).

Provider: ArcGIS REST API + Calcite Design System for data and overlays.

Core Functions:

• Current location tracking and marker clustering.

• Custom icons for categories (parks, libraries, facilities, events).

• Detail popups with description, hours, and links to appointment booking.

• Directions via device-native navigation intents.

• Offline tile cache for City limits region (reduces dependency on live map tiles).

Data Source:

Table gis_locations in Supabase containing:

Field Type Description id uuid unique location ID name text facility name lat/lng numeric coordinates category enum('park','building','event','parking') classification description text summary image_url text thumbnail image amenities jsonb attributes (e.g., wifi, restrooms)

7.3 AR Experience (Augmented Reality)

Framework: ViroReact (Expo-compatible wrapper).

Device Modes:

• Marker-based: Recognizes QR or AR markers placed at buildings or park signs.

• GPS-based: Anchors objects using geolocation when markers unavailable.

Features:

• On-screen 3D overlays for building labels, directions, or park info.

• Accessibility overlays for routes (e.g., wheelchair-friendly paths).

• Pop-up info cards showing metadata from gis_locations.

• AR camera fallback: gracefully disables on unsupported devices.

Content Management:

• AR scene definitions stored in ar_scenes table:

Field Type Description id uuid scene ID location_id uuid FK to gis_locations assets_url text 3D/360 assets (stored in Supabase Storage) triggers jsonb AR markers or GPS triggers last_updated timestamp sync marker

Performance Considerations:

• Progressive asset loading; 360° media streamed or cached locally.

• Asset resolution capped at 2048×1024 to minimize memory use.

• LRU caching for AR scenes on device (max 300 MB).

7.4 Virtual Tours (VR)

Implementation: 360° photos + info overlays using expo-av video player.

Use Cases:

• Park trails with hotspots for distance and elevation data.

• City Hall, libraries, and community centers with interactive labels.

• Historical building tours with embedded captions.

Table: vr_tours

Field Description id unique tour ID name tour title category type (park/building/history)

Field Description assets list of 360° images/videos metadata descriptions, captions, tags is_downloadable boolean for offline mode

7.5 Offline Capability

• Caches selected map tiles, facility data, and VR assets.

• Background service checks connectivity before downloading heavy files.

• Users can manually “preload park tour” in settings.

7.6 GIS Integration Flow

ArcGIS Feature Service → Supabase (gis_locations) → Mobile Map Component → AR/VR Modules → User Interaction/Navigation

Edge Function /gis/sync:

• Polls ArcGIS API nightly for changes.

• Upserts into gis_locations with updated coordinates and metadata.

• Notifies admin dashboard of sync status.

7.7 Accessibility

• Map icons meet 3:1 contrast ratio.

• Voice-over for AR elements (“You are near City Hall, tap to view details”).

• Screen-reader hints for AR markers and VR hotspots.

• Supports both touch and voice navigation.

7.8 Future Extensions

• Heatmap for parking availability.

• 3D building extrusions (Esri SceneLayer integration).

• Dynamic AR scavenger hunts linked to Agents of Discovery missions.

• Offline route guidance using cached GPX data.

8. Dynamic Pages System (Supabase-Backed CMS)

8.1 Objective

Enable non-technical staff to publish, schedule, and iterate content without redeploying the app. All new pages live under the More tab and are assembled from reusable content blocks. Pages render identically across iOS and Android and honor City branding/accessibility requirements.

8.2 Information Architecture

• Fixed tabs remain code-defined: Home, Events, Parks, Services, More.

• Dynamic surface: The More tab reads page menus and external links from Supabase in real time.

• Routing: Each page is addressed by a slug and displayed via a single DynamicPageScreen that renders ordered blocks.

8.3 Supabase Schema (Core CMS Tables)

pages

• id uuid pk

• slug text unique not null (e.g., beach-safety, after-storm-guidance)

• title text not null

• description text (short summary, used in search)

• icon text (optional, name from icon set)

• category text (e.g., “Public Safety,” “Parks & Rec”)

• status enum('draft','review','scheduled','published','archived') default 'draft'

• scheduled_publish_at timestamptz

• author_id uuid (FK → profiles.id)

• reviewer_id uuid (FK → profiles.id)

• created_at/updated_at timestamptz content_blocks

• id uuid pk

• page_id uuid (FK → pages.id on delete cascade)

• type enum('text','image','video','gallery','link','list','faq','event','staff','form','map','html') not null

• content jsonb not null (schema depends on type)

• "order" int not null

• created_at/updated_at timestamptz page_categories (optional taxonomy)

• key text pk (e.g., public-safety)

• label text

• "order" int external_links

• id uuid pk

• label text not null

• url text not null

• provider enum('seeclickfix','justfoia','rec1','utility','civicweb','other') default 'other'

• icon text

• category text

• require_webview boolean default true

• sort int default 0

• is_featured boolean default false

• created_at/updated_at timestamptz page_versions (version history)

• id uuid pk

• page_id uuid

• version int

• delta jsonb (diff payload)

• created_at timestamptz

• created_by uuid

RLS

• anon can select only pages.status in ('published') and their related content_blocks.

• authenticated authors can CRUD drafts and submit for review.

• admin/reviewer roles can approve, schedule, publish, and archive.

• All writes logged via Postgres triggers to an audit_log table.

8.4 Block Payload Templates (plain text examples)

Text Block

"style": "body|lead|caption", "markdown": "Hurricane season runs June–November. Sign up for alerts...", "alignment": "left|center|right"

Image Block

Gallery Block

Link Block

"src": "https://supabase.storage/public/images/beach-flag.png", "alt": "Beach warning flags", "caption": "Beach safety flags"

"items": [ {"src":".../img1.jpg","alt":"Boardwalk"}, {"src":".../img2.jpg","alt":"Pier at sunset"}

"label": "Pay Utility Bill", "url": "https://cc.codb.us/payutilitybill", "require_webview": true

List Block

FAQ Block

Event Block

"variant": "bulleted|numbered|check", "items": ["Bring ID", "Arrive 10 minutes early", "Check parking"]

"items": [ {"q":"How do I request public records?","a":"Use JustFOIA at ..."}, {"q":"Where can I report a pothole?","a":"SeeClickFix link ..."}

"event_id": "uuid", "show_map": true, "cta": {"label": "Add to Calendar", "deep_link": "app://events/123"}

Staff Block

Form Block

Map Block

"staff_id": "uuid", "show_contact": true

"fields": [ {"type":"text","name":"full_name","label":"Full Name","required":true}, {"type":"email","name":"email","label":"Email","required":true}, {"type":"select","name":"topic","label":"Department","options":["Parks","Utilities","FOIA"]}, {"type":"file","name":"attachment","label":"Attachment (optional)"} "submit": {"label":"Send","endpoint":"/forms/submit","success_message":"Thanks! We received your message."}

"center": {"lat":29.2108,"lng":-81.0228}, "zoom": 13, "markers": [{"lat":29.22,"lng":-81.01,"label":"City Hall"}]

HTML Block (sanitized server-side)

8.5 Admin Workflow (Web Portal)

1. Create Draft: Author creates pages record; adds content_blocks via block editor.

2. Preview: Live preview pulls the draft as the app would render it.

3. Review: Status → review. Reviewer comments inline and approves or requests changes.

4. Schedule or Publish:

o Immediate publish sets status to published.

o Scheduled publish sets scheduled_publish_at.

5. Versioning: Publishing writes a snapshot into page_versions with diff against prior version.

6. Archive: Retire outdated content while retaining history.

8.6 Mobile Rendering Pipeline

• Menu assembly:

o SELECT * FROM pages WHERE status='published' ORDER BY category, title;

o SELECT * FROM external_links ORDER BY is_featured DESC, sort ASC;

• Page view:

o Fetch content_blocks for selected page_id, sorted by "order".

o Switch-render components by type.

• Brand compliance: Typography, spacing, and colors applied at component level to prevent off-brand content.

{"html": "<div><strong>Parade Route:</strong> ...</div>"}

• WebView: For link blocks or external_links flagged require_webview=true, open in-app WebView with progress, error, share, and back affordance.

8.7 Offline Strategy

• Cache up to 100 recently viewed pages and associated block assets.

• Stale-while-revalidate: display cached content instantly while refreshing in background.

• “Offline” banner and retry affordance when network unavailable.

• Preload “Critical Info” pages (e.g., emergency procedures) flagged via pages.category='Public Safety'.

8.8 Search & Discovery

• Hybrid search across pages.title, description, and a generated tsvector from text blocks.

• The AI assistant also consumes page content via kb_documents and kb_chunks to provide grounded answers with links back to slug routes.

8.9 Localization (Optional)

• Add locale column to pages and content_blocks, or maintain sibling pages per language with shared group_id.

• Admin portal filters by language; mobile auto-selects based on device locale with manual override.

8.10 Validation & Sanitization

• Server-side Zod validation for block content shapes per type.

• HTML blocks sanitized using a server-side allowlist before persisting.

• File uploads scanned and restricted to approved MIME types.

• Maximum per-page payload guard (e.g., 1.5 MB of media references) to protect low-end devices.

8.11 Observability & Audit

• audit_log table records who changed what and when (page status, block adds/removes).

• Metrics: page impressions, time-on-page, link taps, WebView errors.

• Admin dashboard: top pages, broken link detector, and “orphaned page” reports.

8.12 Acceptance Criteria

• Creating, reviewing, scheduling, and publishing pages requires no app redeploy.

• Dynamic pages render block types: text, image, video, gallery, list, link, faq, event, staff, form, map, html.

• Published content appears in-app within 60 seconds (realtime or polling).

• Offline revisit works for last viewed pages; emergency pages preloaded.

• All HTML sanitized; pages meet WCAG 2.1 AA; tap targets ≥44 px; contrast ≥4.5:1.

• Version history accessible; rollback restores a prior snapshot in ≤2 clicks.

8.13 API Contracts (plain text)

GET /pages?status=published&category={key}&q={search}&limit={n}&offset={m} Returns page list with metadata.

GET /pages/{slug} Returns page metadata + ordered content_blocks.

POST /pages (auth: editor+) Create draft; returns new id and slug.

PATCH /pages/{id} (auth: editor+/reviewer+) Update metadata or status; schedule publish.

POST /pages/{id}/blocks (auth: editor+) Upsert content blocks with "order" and type.

POST /pages/{id}/publish (auth: reviewer+) Publishes immediately; records version snapshot.

9. Integration Architecture and Data Flow

9.1 Objective

Unify the City’s existing public-facing systems under one mobile experience without rebuilding those systems.

Integrations use Supabase Edge Functions and in-app WebViews, providing secure hand-off and consistent branding.

9.2 Integration Model

Integration Type Mechanism Notes

Real-time / API Edge Function → JSON feed → Supabase table

Events, news, GIS data

Interactive Web In-app WebView with secure navigation Utility billing, records, FOIA

Data Sync Nightly pull via Microsoft Graph API SharePoint Lists

Notification Trigger

Edge Function or webhook Event reminders, alerts

All integrations are read-only unless explicitly approved for form submission (e.g., JustFOIA, SeeClickFix).

9.3 Key Third-Party Systems

Service Description Access Type

Integration Endpoint

SeeClickFi x

Citizen issue reporting

WebView + deep link https://seeclickfix.com/web_portal/...

CivicWeb City meeting agendas/minu tes

WebView https://codb.civicweb.net/portal/

Utility Portal

Billing & payments

WebView (secure session) https://cc.codb.us/

Recreation Catalog (Rec1)

Event & facility registration

WebView

+ SSO

option https://secure.rec1.com/FL/daytona-beach-leisure-services/catalog

JustFOIA Public records requests

WebView + form submissi on https://daytonabeachfl.justfoia.com/publicportal/h ome/track

Land Manageme nt (IMS16)

Permitting and zoning

WebView (login required) https://daytonabeach.ims16.com/ims/Account/Log in

Agents of Discovery

AR scavenger hunt API

REST https://agentsofdiscovery.com/mission-data-api

ArcGIS Geospatial data services

REST +

tiles https://codb.maps.arcgis.com/

Microsoft Graph API

SharePoint and Outlook integration

REST +

OAuth2 https://graph.microsoft.com/v1.0/sites/{siteId}/lists /{listId} https://seeclickfix.com/web_portal/ https://codb.civicweb.net/portal/ https://cc.codb.us/ https://secure.rec1.com/FL/daytona-beach-leisure-services/catalog https://secure.rec1.com/FL/daytona-beach-leisure-services/catalog https://daytonabeachfl.justfoia.com/publicportal/home/track https://daytonabeachfl.justfoia.com/publicportal/home/track https://daytonabeach.ims16.com/ims/Account/Login https://daytonabeach.ims16.com/ims/Account/Login https://agentsofdiscovery.com/mission-data-api https://codb.maps.arcgis.com/

Service Description Access Type

Integration Endpoint

Resend Email delivery REST https://api.resend.com

Twilio

SMS / A2P

10DLC

REST https://api.twilio.com

OpenAI AI query completion

REST https://api.openai.com/v1/chat/completions

9.4 WebView Behavior

• Opens in-app modal with navigation toolbar (Back, Forward, Share).

• Shows loading progress indicator (City Blue).

• Displays custom “Offline” message if unreachable.

• Option to open in device browser.

• SSL validation enforced; no mixed-content allowed.

• Session cookies isolated to each service (no cross-site persistence).

Example configuration:

<WebView source={{ uri: 'https://cc.codb.us/' }} startInLoadingState={true} onError={handleWebError} injectedJavaScript={themeInjector} https://api.openai.com/v1/chat/completions

9.5 Theme Injection

Every WebView injects the City’s brand colors and disables pinch-zoom for UI consistency:

9.6 Data Sync: SharePoint → Supabase

Process:

1. Edge Function /sync/sharepoint runs nightly via cron.

2. Queries Microsoft Graph API for each configured List (Events, News, Parks).

3. Maps fields to Supabase schema; upserts using insert ... on conflict.

4. Flags outdated items as archived.

5. Writes sync logs to integration_log table.

integration_log table

Field Description id uuid source e.g., 'SharePoint' items_processed integer items_updated integer duration_ms integer success boolean const themeInjector = ` document.body.style.setProperty('--primary','#154777');

document.body.style.setProperty('--accent','#6FC5D8');

document.body.style.setProperty('--font-family','Century Gothic');

document.querySelectorAll('a').forEach(a=>a.style.color='#6FC5D8');

Field Description message text created_at timestamptz

9.7 Data Flow Diagram (plain text)

[SharePoint Lists]

↓ (Graph API)

[Supabase tables: events, posts, pages]

↓ (Realtime / REST)

[Mobile App & Admin Portal]

↔ (User actions)

[Edge Functions → External APIs (Resend, Twilio, Expo, ArcGIS)]

9.8 Security & Access Control

• OAuth tokens for Microsoft Graph and other APIs stored in Supabase Vault/Secrets.

• Refresh handled by background job; never exposed to clients.

• All outbound requests use city-owned service credentials.

• WebViews restricted to https://*.codb.us, *.daytonabeachfl.justfoia.com, and whitelisted domains.

• Content-Security-Policy enforced via injected headers.

9.9 Error Handling

• Retry policy: 3 exponential retries for API calls; exponential backoff (1 s → 10 s → 30 s).

• Logs written to integration_log and forwarded to Sentry.

• User-facing fallback messages (“Service temporarily unavailable”).

• Admin alert if failure > 3 consecutive runs.

9.10 Performance Targets

• API response < 2 s average.

• WebView load < 4 s over LTE.

• Sync job completion < 10 min for ≤10 k records.

• Zero unauthenticated write access from client apps.

9.11 Acceptance Criteria

• All integrations functional and theme-consistent inside the app.

• APIs reach ≥ 99 % availability.

• Sync operations succeed without manual intervention.

• Admin logs show < 1 % error rate.

• All third-party endpoints documented in Appendix D.

10. Continuous Integration / Continuous Deployment (CI/CD)

10.1 Objective

Ensure that every code change, configuration update, and content migration moves from development → preview → production through a repeatable, automated process.

All automation runs in City-owned GitHub Actions pipelines and deploys to Expo EAS and Vercel.

10.2 Environments

Environment Purpose Branch Build Type Distribution

Development local + internal testing dev/* debug Expo Go & Vercel preview

Environment Purpose Branch Build Type Distribution

Preview stakeholder review main (pre-release) release-candidate

EAS preview channel / Vercel preview URL

Production public deployment tagged release (vX.Y.Z) signed production

App Store / Play Store / live Vercel domain

10.3 GitHub Actions Workflow

Trigger Events

• push to main or dev/*

• pull_request opened / merged

• manual dispatch for hotfix builds

Pipeline Stages (yaml)

Artifacts

• EAS build URLs for iOS/Android

• Vercel deployment preview link

• Test reports (Jest coverage ≥ 70 %) jobs:

lint_test:

run: npm run lint && npm run test build_mobile:

run: eas build --profile ${PROFILE} deploy_web:

run: vercel --prod --token ${VERCEL_TOKEN} migrate_db:

run: supabase db push

• Supabase migration log

10.4 Expo EAS Configuration

eas.json

Profiles

• Development: debug APK/IPA for internal QA

• Preview: pre-release builds with OTA enabled

• Production: signed AAB / IPA with manual store submission

OTA Updates

• Non-breaking JS/asset changes via expo publish.

• Each channel mapped to matching build profile.

10.5 Vercel Deployment Pipeline

• GitHub → Vercel integration (auto-deploy on merge).

• Branch preview URLs: branch-name.citydaytona.vercel.app.

• Environment Variables: stored per environment (Dev/Preview/Prod).

• Automated previews for pull requests; approved PR → production promote.

"build": { "development": { "distribution": "internal", "channel": "dev" }, "preview": { "distribution": "internal", "channel": "preview" }, "production": { "distribution": "store", "channel": "stable" }

• Rollback via Vercel dashboard (one-click revert).

10.6 Supabase Deployment

• Schema migrations checked into supabase/migrations/.

• Apply migrations automatically in CI via supabase db push.

• Seed data for development in supabase/seed.sql.

• Edge Functions deployed via supabase functions deploy *.

• RLS Policies tested in CI to prevent accidental privilege escalation.

10.7 Environment Variables & Secrets

Validated via Zod schema at runtime; missing key fails build. (nginx)

Secrets Storage

• GitHub Secrets for CI.

• Vercel Env Manager for web.

• Expo EAS Secrets for mobile.

RESEND_API_KEY

TWILIO_ACCOUNT_SID

TWILIO_AUTH_TOKEN

TWILIO_MESSAGING_SERVICE_SID

OPENAI_API_KEY

SUPABASE_URL

SUPABASE_ANON_KEY

SUPABASE_SERVICE_ROLE_KEY

ARCGIS_API_KEY

AGENTS_OF_DISCOVERY_API_KEY

VERCEL_TOKEN

• Supabase Vault for runtime tokens.

10.8 Versioning & Tagging

• Semantic versioning vMAJOR.MINOR.PATCH.

• Automatic tagging on main merge after tests pass.

• Each build injects version metadata (appVersion, buildDate, commitHash) into About screen and API headers.

10.9 Rollbacks & Recovery

• Web: Vercel instant revert (1-click).

• Mobile: Publish prior OTA bundle channel revert.

• Database: pg_dump nightly snapshot + point-in-time restore (24 h window).

• AI Embeddings: retain last two vector sets for fallback search.

10.10 Security & Access

• Branch protection rules: PR review + checks required before merge.

• CI runners ephemeral (no persistent secrets).

• Build signing keys stored in City Keychain only.

• Post-deploy smoke tests verify API and push notifications before marking “green.”

10.11 Monitoring & Alerting

• Sentry: captures errors for mobile, web, and Edge Functions.

• UptimeRobot / Vercel Insights: availability monitoring.

• Supabase Logs: query latency + error rate tracking.

• Slack/email alerts to City IT on pipeline failure or uptime drop.

10.12 Acceptance Criteria

• Commit → build → deploy pipeline runs < 10 min.

• 100 % of source under CI coverage.

• Rollback tested and documented.

• All credentials in City-owned secrets managers.

• Each build automatically logged and auditable for 30 days.

11. Testing & Quality Assurance Framework

11.1 Objective

Guarantee that every component—from Edge Functions to mobile UI—meets reliability, accessibility, and performance targets before deployment. Testing runs automatically in CI/CD and manually during User Acceptance Testing (UAT).

11.2 Testing Layers

Layer Tools / Frameworks Focus

Unit Tests Jest, React Testing Library Component logic, utility functions

Integration Tests Cypress (web), Detox (mobile) API interaction, auth flow, navigation

End-to-End Tests Playwright + Expo E2E Full user journeys and offline behaviors

Performance Tests

Lighthouse (web), Expo Profiler Launch times, FPS, memory usage

Accessibility Tests axe-core, react-native-accessibility-engine

WCAG 2.1 AA compliance

Security Tests npm audit, OWASP ZAP scans Dependency & API vulnerability detection

Layer Tools / Frameworks Focus

Load Tests k6 (Edge Functions & Supabase) Simulated concurrent users

11.3 Unit Testing Standards

• Coverage Target: ≥70% for utilities and API functions.

• Test Cases: Each function tested for both success and failure paths.

• Snapshots: UI components snapshot-tested per theme (light/dark).

• Mocking: External APIs (Supabase, Twilio, OpenAI) stubbed via MSW (Mock Service Worker).

• Naming Convention: *.test.ts(x) colocated with source.

Example Unit Test (plain text)

11.4 Integration Testing

• Validate Supabase Auth, data queries, and offline caching.

• Mock Supabase API with replayed JSON fixtures.

• Test “More” tab rendering for all block types (text, image, form, map, etc.).

• Confirm external links open in WebView and return safely to app.

• Validate notification subscriptions update correctly in backend.

11.5 End-to-End (E2E) Testing

describe('formatEventDate', () => { it('returns localized string', () => { expect(formatEventDate('2025-07-04T19:00Z')).toContain('July 4, 2025');

Scope

• Full user login → browse → subscribe → receive notification → log out.

• Offline/online transitions.

• Multilingual toggles.

• Accessibility navigation (screen reader, large text).

Tools

• Detox: Mobile test runner integrated with Expo builds.

• Playwright: For web admin (Next.js portal).

• CI triggers nightly regression suite.

Example (plain text)

11.6 Accessibility (A11y) Testing

Compliance with WCAG 2.1 AA is mandatory.

Checklist:

Category Requirement

Color contrast ≥ 4.5:1 for text, ≥ 3:1 for large text

Tap targets ≥ 44 × 44 px

Keyboard navigation Supported in web admin scenario('User subscribes to event alerts', async () => { await login('test@user.com', 'password');

await tap('Settings');

await toggle('Emergency Alerts');

await expect(Toast('Preferences updated')).toBeVisible();

Category Requirement

Voice control Compatible with iOS VoiceOver & Android TalkBack

Dynamic text System font scaling respected

Alt text All images & AR markers include alt/description fields

Motion sensitivity Reduced motion toggle disables animations

Accessibility audits run per release using axe-core and React Native Accessibility Engine.

11.7 Performance Testing

Targets

• App launch ≤ 3 s.

• Screen transitions ≤ 500 ms.

• API round-trip ≤ 2 s p95.

• Battery drain ≤ 3 % per hour continuous use.

• Crash-free sessions ≥ 99 %.

Method

• Automated via Expo Profiler (CPU/memory/FPS).

• Web via Lighthouse (performance score ≥ 90).

• Load testing of Edge Functions with k6 simulating 1,000 concurrent users.

11.8 Security & Penetration Testing

• Dependency scanning: npm audit --production on every CI run.

• API fuzzing: k6 scripts simulate malformed payloads.

• Static Analysis: ESLint + TypeScript strict mode + dependency review.

• Penetration test: Annual audit using OWASP Top 10 methodology.

• Vulnerability Disclosure Program: optional extension for public bug reports.

11.9 User Acceptance Testing (UAT)

Conducted by City IT and Communications staff with real data.

Test cases mirror resident workflows and accessibility needs.

Process

1. Build deployed to EAS “preview” channel.

2. UAT script executed and documented.

3. Issues tracked in GitHub Projects board.

4. Fixes merged and re-verified before production release.

Acceptance Gate

• All critical and high-severity defects resolved.

• Accessibility and performance thresholds met.

• Stakeholder sign-off recorded in meeting minutes.

11.10 Regression Testing

• Run nightly using CI on main branch.

• Auto-generated test matrix covers major devices (iPhone SE, iPad, Pixel 7).

• Failure triggers Slack/email alert to development lead.

11.11 Test Data & Environments

• Separate Supabase instances for Dev, QA, and Prod.

• Masked datasets (no personal info).

• Synthetic users for notifications and AI testing.

• Fixtures version-controlled (/tests/fixtures/).

11.12 Acceptance Criteria

• 100% of defined test cases executed and documented.

• All blocking defects resolved before go-live.

• Crash-free session rate ≥ 99 %.

• Accessibility audit passed (axe-core score ≥ 95).

• Automated CI tests run successfully before each deployment.

12. Figma Design System, Components & Branding Enforcement

12.1 Objective

Establish a consistent, reusable, and WCAG-compliant design system for all app interfaces.

This ensures that updates, accessibility fixes, and branding changes cascade automatically across mobile and web assets.

12.2 Figma Workspace Structure

Figma Team: City of Daytona Beach – Digital Experience

Files:

1. Design System (Master Library) o Color tokens, typography, icons, elevation, grid system.

o Reused across Mobile App and Admin Portal files.

2. Mobile App (React Native Prototype) o Screen flows for Home, Events, Parks, Services, More, Chat, and Notifications.

3. Admin Portal (Next.js Prototype) o Layouts for Dashboard, Posts, Events, Pages, Notifications, and Settings.

Version Control:

Design tokens (JSON export) committed to packages/ui-tokens/ in the GitHub monorepo.

Developers sync using figma-tokens plugin or REST API.

12.3 Design Tokens

Color Palette

Token Hex Usage color-primary-red #EF3E3D Alerts, destructive buttons color-primary-orange #FAA21B Warnings, highlights color-primary-blue #6FC5D8 Links, accents color-secondary-blue #154777 Headers, nav backgrounds color-light-gray #F1F2F2 Card backgrounds, borders color-text-dark #1E1E1E Body text color-text-light #FFFFFF On dark backgrounds

Typography

Style Font Weight Use

Display Dunbar Text Extra Bold 800 Banners, titles

Heading Century Gothic 700 Section headers

Body Century Gothic 400 General text

Accent Yellowtail Regular 400 Decorative headings

Spacing

• 4 px base grid.

• 8 px rhythm for padding/margins.

• Components adhere to 8/16/24 px intervals for consistent spacing.

Elevation

• elevation-1: subtle 2 dp shadow for cards.

• elevation-2: 4 dp for modals and FABs.

Border Radius

• Buttons: 8 px

• Cards: 12 px

• Modal corners: 16 px

12.4 Component Library

Core Components (shared React Native + Web)

Component Description

Button Primary, Secondary, Destructive, Disabled variants

Card Rounded container with shadow + padding

TabBar Bottom nav with icons (24–28 px)

InputField Label, helper text, error states

Switch Toggle for subscription preferences

ListItem Avatar, title, description layout

Modal For confirmation dialogs

Toast Inline confirmation alerts

Badge Status indicators (color-coded)

FormBlock Composite component rendering forms from schema

State Variants

• Default / Hover / Active / Disabled / Loading.

Interactive Tokens

• Hover states lighten 5%.

• Pressed states darken 10%.

• Focus ring: 2 px Primary Blue outline.

12.5 Accessibility Integration

All components meet WCAG 2.1 AA and are tested for:

• Contrast ratio compliance.

• Keyboard and screen reader focus order.

• Font scaling (Dynamic Type / Android font scaling).

• ARIA role annotation in Admin Portal (e.g., role="dialog", aria-live="polite").

12.6 Mobile Screen Prototypes

Each Figma screen maps directly to a React Native route.

Screen Groups:

• Home: Carousel banners, featured news, quick actions.

• Events: Calendar, list, and event details.

• Parks: Map view, details, AR/VR entry points.

• Services: Category cards, service directory.

• More: Dynamic pages list + external links.

• AI Chat: Conversational layout with mic + playback buttons.

• Notifications: Preferences toggles per topic.

• WebView: Loader, retry, share overlay.

• System: Splash, Login, Profile, 404.

Prototype flows link across tab navigation and modals.

12.7 Admin Portal Design

Layout:

• Sidebar (Secondary Blue background).

• Top bar with user avatar + breadcrumbs.

• Content area with card grid (Light Gray).

• Font: Century Gothic.

• Primary CTAs: Secondary Blue background, white text.

Core Screens

Screen Description

Dashboard Metrics, sync logs, notifications overview

Posts CRUD table with preview

Events Calendar + list + event editor

Pages Drag-and-drop block editor

Links Manage external links and featured shortcuts

Notifications Compose + schedule system

AI Knowledge View indexed docs and reindex crawler

Settings Branding tokens, environment keys

12.8 Figma-to-Code Mapping

Figma Component React Native Component Notes

Button / Primary <Button variant="primary" /> color = Secondary Blue

Card / Default <Card /> elevation = 2dp

Input / Text <TextInput /> autoFocus optional

Figma Component React Native Component Notes

ListItem / Icon <ListItem icon={<Icon />}/> align with RN Paper style

Tab / Navigation <BottomTabNavigator /> colors via Design Tokens

Tokens sync weekly via figma-tokens CLI.

12.9 Branding Enforcement

• Any visual changes (fonts, colors, spacing) must be updated in the Figma Design System file, not directly in code.

• City Communications must approve design modifications before release.

• QA verifies pixel parity between design mockups and running builds.

• Branding diff report generated using visual regression testing (Percy/Screener).

12.10 Deliverables

• .fig source files for all design assets.

• JSON exports of tokens (tokens/color.json, tokens/typography.json).

• PNG assets for app stores (icons, splash, feature graphics).

• Accessibility audit report per release.

• Figma link to interactive prototype showing all navigation paths.

13. Security, Privacy & Compliance Framework

13.1 Objective

Ensure all data, systems, and integrations related to the Daytona Beach Civic Engagement Platform are secured by design, in line with CJIS, NIST 800-53, and OWASP Mobile Top 10 standards.

The goal is to deliver transparency, data integrity, and strong privacy for all users while maintaining system resilience and auditability.

13.2 Security Principles

1. Least Privilege:

Every user, function, and API key is granted only the permissions absolutely necessary for its role.

2. Defense in Depth:

Layered protection—encryption, firewalls, authentication, and RLS (Row Level Security) policies.

3. Zero Trust Posture:

No system or user is inherently trusted; continuous authentication and session validation are enforced.

4. Auditability:

All administrative actions and data access events are logged and immutable for 12 months minimum.

5. Fail-Safe Defaults:

Unauthenticated or invalid requests are denied by default.

13.3 Authentication & Access Control

Supabase Auth:

• Supports Email/Password, Microsoft Single Sign-On, and optional Social (Google, Apple) logins.

• Tokens: short-lived JWTs (max 1 hr) with automatic refresh via secure refresh tokens.

• Multi-Factor Authentication (MFA) optional for admin and staff accounts.

• All API routes validated via server-side JWT middleware.

Role-Based Access Model

Role Permissions

Anonymous Read-only access to public content

Authenticated User Access personal subscriptions, preferences, RSVP

Role Permissions

Content Editor CRUD on pages, posts, events

Reviewer Approve and schedule content

Administrator Manage users, notifications, integrations

System Execute Edge Functions (Resend, Twilio, AI)

Session Management

• Idle session timeout: 30 min for admin portal, 1 hr for mobile app.

• Device sessions revocable by user or admin.

• Supabase refresh_token invalidated on logout.

13.4 Encryption & Data Security

Layer Technology Notes

Transport HTTPS (TLS 1.3) All traffic encrypted end-to-end

Storage AES-256 at rest (Supabase Postgres + Storage)

Managed…