# phuturedigital/phuture-platform architecture

> Architecture diagram of the GitHub repository phuturedigital/phuture-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phuturedigital/phuture-platform
- Repository: https://github.com/phuturedigital/phuture-platform

## Overview

1. **Repo shape**
   - This is a monorepo for multiple product surfaces under one platform umbrella: `website`, `phuture-os`, `livin`, `pulse`, and `zwakala`.
   - The common pattern is a TypeScript/Vite frontend per app, backed by Supabase for auth, database, storage, and serverless edge logic.

2. **Product boundaries**
   - `apps/website` is the public marketing/site layer: home, services, portfolio, audit funnel, quote/cart/lead capture, and a small admin area.
   - `apps/phuture-os` is the main internal operating system for the business: multi-tenant admin/client portals, onboarding, billing, bookings, CRM, messaging, integrations, analytics, support, and system health.
   - `apps/livin` is a property/community app: listings, saved properties, suburb alerts, neighborhood intelligence, host/property workflows.
   - `apps/pulse` is a survey/assessment app: guided question flow, consent, resume, insight and admin analytics/export.
   - `apps/zwakala` is an events/discovery app: events, venues, follows, RSVPs, notifications, venue dashboards, and admin tooling.

3. **Frontend architecture**
   - Each app uses a client-side React UI with route/page components and smaller feature components.
   - Auth, permissions, consent, and “protected route” concerns are handled in-app through contexts/hooks/components rather than a separate BFF.
   - Tailwind/Vite/TypeScript are the shared frontend stack; each app is independently deployable.

4. **Supabase as the shared backend**
   - Supabase is the primary backend boundary across the repo.
   - Frontends talk directly to Supabase from the browser for CRUD, auth, and real-time-style app state.
   - The `supabase/` directories contain SQL migrations, RLS policies, triggers, cron setup, and edge functions, showing that domain logic is split between client and database/serverless layers.

5. **Data model and access control**
   - The architecture is strongly schema-driven: many timestamped migrations evolve tables, views, triggers, indexes, and policies over time.
   - Row-level security is a major design constraint, especially in `phuture-os`, which has explicit tenant isolation, role/membership modeling, and admin bypass policies.
   - `packages/supabase` contains shared generated database types, acting as the typed contract between Supabase schema and the apps.

6. **Serverless and event-driven flows**
   - Supabase edge functions handle privileged operations, webhooks, scheduled jobs, and side effects.
   - In `phuture-os`, functions cover integrations and automations for Paystack, WhatsApp, LinkedIn, Meta, Google Ads, Canva, Google Search Console, booking notifications, onboarding, intake, support, and processing jobs.
   - Several migrations install cron jobs and trigger-based workflows, so many flows are database/event initiated rather than manually invoked from the UI.

7. **Domain-specific backend behavior**
   - `livin` has functions and tables around suburb alerts and neighborhood intelligence, implying notification and enrichment flows around property neighborhoods.
   - `pulse` persists survey responses/progress and computes insights/recommendations, with admin exports and reporting as a secondary workflow.
   - `zwakala` centers on event discovery, follows, saved items, notifications, and venue moderation/claim flows.
   - `website` has lead capture, audit-share/reporting, and portfolio/order flows, backed by Supabase tables and admin UI.

8. **External service integration layer**
   - The system integrates with payment, messaging, ads, and creative services: Paystack, WhatsApp, Meta/Facebook, LinkedIn, Google Ads, Canva, Google Search Console, and email delivery.
   - These integrations are mostly isolated behind Supabase functions and shared helper modules, so the browser never directly owns secrets or provider credentials.

9. **Outbound processing**
   - `outbound-functions/` is a separate serverless worker-style area for batch or rendering-heavy tasks such as audits, daily pipelines, mockup generation, image fetching, and email enrichment.
   - This suggests a second async boundary beyond Supabase edge functions for jobs that are more offline, pipeline-driven, or rendering-centric.

10. **Operational and deployment setup**
   - GitHub Actions run Supabase CI/deploy workflows, indicating schema/function deployment is treated as infrastructure, not just app code.
   - Each app also has Vercel config, so frontends are likely deployed independently.
   - The repo includes demo-account seed functions, test helpers, and archived migrations, showing a production system with repeatable environment setup and historical schema evolution.

11. **How to draw the architecture**
   - Draw each app as an independent React frontend layer.
   - Put Supabase at the center as the shared data/auth/backend platform, with DB migrations, RLS, triggers, storage, and edge functions around it.
   - Add external integrations off to the side, connected mostly through edge functions and cron/webhook flows.
   - Show `packages/supabase` as the shared type contract, and `outbound-functions` as a separate async/job-processing lane.

Main entry points: [`apps/phuture-os/supabase/functions`](https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/phuture-os/supabase/functions) (edge functions), [`packages/supabase/src/database.types.ts`](https://github.com/phuturedigital/phuture-platform/blob/version_4/packages/supabase/src/database.types.ts) (supabase types), [`apps/website`](https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/website) (website), [`apps/phuture-os`](https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/phuture-os) (phuture-os)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontends["Frontends"]
  node_website["website<br/>React marketing app"]
  node_phutureos["phuture-os<br/>React ops app"]
  node_livin["livin<br/>React property app"]
  node_pulse["pulse<br/>React survey app"]
  node_zwakala["zwakala<br/>React events app"]
end

subgraph group_backend["Supabase platform"]
  node_supabase[("Supabase<br/>shared backend")]
  node_migrations["migrations<br/>schema evolution"]
  node_rls{{"RLS policies<br/>access control"}}
  node_triggers{{"triggers & cron<br/>event workflow"}}
  node_edgefuncs["edge functions<br/>serverless actions"]
end

subgraph group_shared["Shared code"]
  node_sharedtypes["supabase types<br/>typed contract<br/>[database.types.ts]"]
end

subgraph group_async["Async workers"]
  node_outbound["outbound-functions<br/>worker lane"]
end

subgraph group_external["External services"]
  node_paystack(("Paystack<br/>payments"))
  node_whatsapp(("WhatsApp<br/>messaging"))
  node_google(("Google services<br/>ads/search"))
  node_meta(("Meta<br/>ads platform"))
  node_linkedin(("LinkedIn<br/>ads/social"))
  node_canva(("Canva<br/>creative api"))
  node_email(("email delivery<br/>notification"))
end

node_website -->|"CRUD/auth"| node_supabase
node_phutureos -->|"core data"| node_supabase
node_livin -->|"property data"| node_supabase
node_pulse -->|"responses"| node_supabase
node_zwakala -->|"events data"| node_supabase
node_website -->|"types"| node_sharedtypes
node_phutureos -->|"types"| node_sharedtypes
node_livin -->|"types"| node_sharedtypes
node_pulse -->|"types"| node_sharedtypes
node_zwakala -->|"types"| node_sharedtypes
node_migrations -->|"schema"| node_supabase
node_rls -->|"guardrails"| node_supabase
node_triggers -->|"automation"| node_supabase
node_edgefuncs -->|"serverless"| node_supabase
node_edgefuncs -->|"billing"| node_paystack
node_edgefuncs -->|"messages"| node_whatsapp
node_edgefuncs -->|"ads/search"| node_google
node_edgefuncs -->|"campaigns"| node_meta
node_edgefuncs -->|"publishing"| node_linkedin
node_edgefuncs -->|"designs"| node_canva
node_edgefuncs -->|"notifications"| node_email
node_phutureos -->|"async jobs"| node_outbound
node_website -->|"rendering"| node_outbound
node_supabase -->|"invokes"| node_edgefuncs
node_supabase -->|"events"| node_triggers

click node_website "https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/website"
click node_phutureos "https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/phuture-os"
click node_livin "https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/livin"
click node_pulse "https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/pulse"
click node_zwakala "https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/zwakala"
click node_migrations "https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/phuture-os/supabase/migrations"
click node_edgefuncs "https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/phuture-os/supabase/functions"
click node_sharedtypes "https://github.com/phuturedigital/phuture-platform/blob/version_4/packages/supabase/src/database.types.ts"
click node_outbound "https://github.com/phuturedigital/phuture-platform/tree/version_4/outbound-functions"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_website,node_phutureos,node_livin,node_pulse,node_zwakala toneBlue
class node_supabase,node_migrations,node_rls,node_triggers,node_edgefuncs toneAmber
class node_sharedtypes toneMint
class node_outbound toneRose
class node_paystack,node_whatsapp,node_google,node_meta,node_linkedin,node_canva,node_email toneIndigo
```

## Components

### Frontends

Independent React/Vite product surfaces

- [website](https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/website): React marketing app · Public site with services, portfolio, audit funnel, quote and lead capture, plus small admin tools · `apps/website`
- [phuture-os](https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/phuture-os): React ops app · Internal operating system for multi-tenant admin, client portals, onboarding, billing, CRM, support, and integrations · `apps/phuture-os`
- [livin](https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/livin): React property app · Property and community experience for listings, saved properties, suburb alerts, and host workflows · `apps/livin`
- [pulse](https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/pulse): React survey app · Guided assessment flow with consent, progress resume, insights, and admin reporting · `apps/pulse`
- [zwakala](https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/zwakala): React events app · Events and venues discovery with follows, RSVPs, notifications, venue dashboards, and moderation · `apps/zwakala`

### Supabase platform

Shared database, auth, storage, and edge logic

- **Supabase**: shared backend · Central platform for auth, database, storage, RLS, triggers, cron, and edge functions
- [migrations](https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/phuture-os/supabase/migrations): schema evolution · Timestamped SQL migrations that define tables, views, policies, triggers, and indexes across products · `apps/phuture-os/supabase/migrations`
- **RLS policies**: access control · Tenant isolation and per-app authorization enforced in the database
- **triggers & cron**: event workflow · Database-triggered and scheduled workflows that drive notifications, sync, and cleanup
- [edge functions](https://github.com/phuturedigital/phuture-platform/tree/version_4/apps/phuture-os/supabase/functions): serverless actions · Privileged operations, webhooks, integrations, and scheduled jobs · `apps/phuture-os/supabase/functions`

### Shared code

Typed contracts and cross-app modules

- [supabase types](https://github.com/phuturedigital/phuture-platform/blob/version_4/packages/supabase/src/database.types.ts): typed contract · Generated database types shared between apps and the Supabase schema · `packages/supabase/src/database.types.ts`

### Async workers

Offline and rendering-heavy processing lane

- [outbound-functions](https://github.com/phuturedigital/phuture-platform/tree/version_4/outbound-functions): worker lane · Separate async processing area for audits, pipelines, mockups, and enrichment · `outbound-functions`

### External services

Third-party providers used through serverless integrations

- **Paystack**: payments · Payment and billing provider
- **WhatsApp**: messaging · Messaging and notification channel
- **Google services**: ads/search · Google Ads, Search Console, and related analytics or OAuth flows
- **Meta**: ads platform · Meta/Facebook OAuth, campaigns, and reporting
- **LinkedIn**: ads/social · Campaign and posting integrations
- **Canva**: creative api · Design creation and export workflows
- **email delivery**: notification · Outbound email and digest delivery

## Connections

- website → Supabase: CRUD/auth · Browser app talks directly to Supabase for leads, portfolio, audit, and admin data
- phuture-os → Supabase: core data · Primary backend boundary for tenant, CRM, billing, booking, and support state
- livin → Supabase: property data · Listings, profiles, saves, and suburb alert state
- pulse → Supabase: responses · Survey progress, consent, and result persistence
- zwakala → Supabase: events data · Events, venues, follows, RSVPs, notifications, and moderation data
- website → supabase types: types · Uses generated database types as the typed client contract
- phuture-os → supabase types: types · Uses generated database types as the typed client contract
- livin → supabase types: types · Uses generated database types as the typed client contract
- pulse → supabase types: types · Uses generated database types as the typed client contract
- zwakala → supabase types: types · Uses generated database types as the typed client contract
- migrations → Supabase: schema · Defines and evolves the shared database and policy surface
- RLS policies → Supabase: guardrails · Row-level security constrains tenant and role access
- triggers & cron → Supabase: automation · Database events and cron jobs drive side effects and sync
- edge functions → Supabase: serverless · Privileged logic runs close to the data boundary
- edge functions → Paystack: billing · Payment initialization, verification, onboarding, and webhook handling
- edge functions → WhatsApp: messages · Messaging setup, webhooks, and send flows
- edge functions → Google services: ads/search · OAuth, metrics, and conversions for Google services
- edge functions → Meta: campaigns · OAuth, campaign updates, and performance fetches
- edge functions → LinkedIn: publishing · Campaign creation, posting, and reporting flows
- edge functions → Canva: designs · Design generation and export/post workflows
- edge functions → email delivery: notifications · Booking, digest, onboarding, and reminder emails
- phuture-os → outbound-functions: async jobs · Routes heavier audit, mockup, and pipeline work to the worker lane
- website → outbound-functions: rendering · Uses offline generation for audit and social preview outputs
- Supabase → edge functions: invokes · Database/webhook/cron flows trigger serverless actions
- Supabase → triggers & cron: events · Triggers and scheduled jobs are installed within the platform boundary
