KTP Life App Architecture

Goal

Help contributors understand how a member action moves through the app without publishing credentials, production identifiers, exploitable security details, or member records.

System context

KTP member
    |
    v
Expo / React Native client
    |-- Expo Router ---------------------- screens and navigation
    |-- Zustand -------------------------- session and lightweight client state
    |-- TanStack Query ------------------- remote data, caching, and mutations
    |
    +--> Supabase Auth ------------------- authentication and session lifecycle
    +--> Supabase Postgres --------------- chapter, member, event, RSVP, and attendance data
    +--> Supabase Storage ---------------- approved profile media and résumés
    +<-> Supabase Realtime --------------- event-change invalidation
    +--> Supabase Edge Functions --------- privileged or coordinated server workflows
    +--> Expo Push Service --------------- device notification delivery

Server-side Google Calendar synchronization --> Supabase event data
Separate KTP management dashboard -----------> approved administrative workflows

The mobile client reads synchronized event records rather than calling Google Calendar directly from each device.

Client layers

Layer	Responsibility
Routes and screens	Navigation and screen-level composition using Expo Router
Components	Reusable presentation and interaction elements
Hooks	Remote queries, mutations, authentication lifecycle, uploads, media access, realtime, and connectivity
Domain utilities	Validation, dates, routing, QR handling, formatting, and configuration
State stores	Session/profile/chapter coordination and transient UI state
Transformers	Convert backend-shaped records into client domain objects and back

Keep network and data conversion out of screen components. The transformation boundary is especially important for nullable joins, numeric values, and date-only fields that behave differently across time zones.

Major runtime lifecycle

1. The root application loads providers, fonts, and safe-area behavior.
2. The client restores the existing Supabase session.
3. Authentication changes and foreground/background token refresh are registered.
4. The signed-in member profile and selected chapter are loaded.
5. Event updates subscribe to realtime invalidation.
6. A physical device may register for approved push notifications.
7. Centralized auth bootstrap routes the user to signed-in or signed-out screens.

Product data domains

The client documentation describes these logical domains:

• member profiles, chapter affiliation, roles, and pledge classes;
• academic, contact, social, résumé, and internship profile information;
• chapter metadata and chapter selection;
• calendar events and event status;
• RSVP responses;
• attendance records; and
• device notification registrations.

This list is an architectural summary, not permission to expose or reuse the data. Field-level purpose, visibility, retention, correction, and deletion rules must be approved in the restricted data map.

Trust boundaries

• The app interface may hide or show controls based on a loaded role, but the server must authorize every privileged read and write.
• Attendance and RSVP operations must identify the authenticated member on the server rather than trusting a submitted user identifier.
• Short-lived QR behavior reduces accidental reuse but must be backed by server validation.
• Public client configuration is not a place for service-role keys, signing secrets, calendar credentials, or recovery information.
• Storage ownership should use immutable authenticated identifiers and prevent one member from overwriting another member's files.
• Development, beta, and production environments need distinct ownership and change controls.

Repository boundaries

Source of truth	What belongs there
Mobile client repository	Routes, components, hooks, domain utilities, client tests, app configuration, and feature-adjacent developer docs
Backend source repository	Versioned database migrations, server authorization policies, functions, local development, policy tests, and deployment history
Calendar synchronization source	Server job, deployment, monitoring, retry behavior, and runbook
Management dashboard repository	Administrative workflows, role behavior, tests, and dashboard releases
Documentation repository	Public-safe product overview, architecture, setup, team model, chapter onboarding, and release summaries
Restricted operations system	Production service inventory, administrators, credentials, signing, recovery, incidents, and sensitive logs

The canonical organization-owned location and maintainer for each source still need to be recorded.

Architecture decisions to document next

Use short architecture decision records in the app or backend source repositories for:

• authoritative version and release numbering;
• identity and role model;
• profile and résumé visibility;
• server-side attendance validation;
• event synchronization and cancellation behavior;
• data retention and deletion;
• organization ownership of Expo, stores, Supabase, domains, and CI; and
• supported web, iOS, and Android targets.

Publish the decision summary here only when it is safe and useful to chapters.

Public-content review

• [ ] Diagram describes components without production identifiers or private URLs
• [ ] No schemas, policies, credentials, member records, or sensitive logs are copied here
• [ ] Security expectations are stated without publishing exploit instructions
• [ ] Repository and system owners are current
• [ ] Planned architecture is not presented as deployed behavior