ComuniTEA App Architecture: Modules and Navigation

ComuniTEA is organised as a feature-driven Expo application. The codebase separates domain logic into self-contained feature modules under features/, while shared infrastructure — Supabase client, constants, Zustand stores, React contexts, and reusable components — lives at the root level. Navigation is handled entirely by Expo Router’s file-based routing, and all global runtime state is managed through a layered combination of Zustand stores (for lightweight, persisted client state) and React Context providers (for auth, child profile, timers, theming, and network status). The Supabase backend provides authentication, a PostgreSQL database, object storage for custom pictogram images, and a set of Deno-based Edge Functions for AI and TTS features.

Directory Structure

comunitea/
├── app/                        # Expo Router file-based routes
│   ├── _layout.tsx             # Root stack + all context providers
│   ├── index.tsx               # App entry / splash redirect
│   ├── login.tsx               # Email auth screen
│   ├── voice-selection.tsx     # First-run voice profile picker
│   ├── onboarding.tsx          # Child profile setup wizard
│   ├── tutorial/               # Interactive tutorial (G1/G2 + G3 tracks)
│   ├── (tabs)/                 # Tab navigator (tablero, ejercicios, perfil)
│   │   ├── _layout.tsx         # Tabs layout with themed tab bar
│   │   ├── tablero.tsx         # Communication board screen
│   │   ├── categorias.tsx      # Category browser
│   │   ├── ejercicios.tsx      # Exercises hub
│   │   └── perfil.tsx          # Child profile & settings
│   ├── category/[id].tsx       # Dynamic sub-category pictogram grid
│   ├── ejercicios/             # Nested exercise routes (G2 + G3)
│   │   ├── grupo2/             # G2 exercise levels and individual exercises
│   │   └── grupo3/             # G3 exercise levels and individual exercises
│   ├── sentences.tsx           # Saved sentence history
│   ├── report.tsx              # Caregiver session report
│   ├── settings.tsx            # App settings (parental gate protected)
│   ├── vocabulary-manager.tsx  # Custom pictogram manager
│   ├── activity-editor.tsx     # Guided activity creator
│   ├── activity-run.tsx        # Guided activity runner
│   ├── game.tsx                # Gamified pictogram matching
│   └── team-manager.tsx        # Multi-role team manager
├── features/                   # Domain feature modules
│   ├── tablero/                # Communication board logic
│   ├── vocabulario/            # Vocabulary data and pictogram hooks
│   ├── ejercicios/             # Exercise data and progress hooks
│   ├── perfil/                 # Profile and report hooks
│   └── tutorial/               # Tutorial state and voice assets
├── stores/                     # Zustand global state stores
├── lib/                        # Supabase client, storage keys, utilities
├── context/                    # React Context providers
├── components/                 # Shared UI components
├── constants/                  # Design tokens, vocabulary data, audio maps
├── assets/
│   └── audio/                  # Bundled MP3 audio (femenina/ + masculina/)
└── supabase/
    ├── config.toml             # Local Supabase CLI config
    ├── migrations/             # Ordered SQL schema migrations
    └── functions/              # Deno Edge Functions

Feature Modules

Each subdirectory of features/ is a self-contained domain module that exposes a public API through its index.ts. Screens in app/ import only from these public surfaces — never directly from a sibling feature’s internals.

Module	Path	What it exports and does
tablero	`features/tablero/`	`useTablero`, `useFrase`, tablero data, and voice-frase utilities. Owns the pictogram board state: which categories are active, which pictograms are visible, and how pictogram selections flow into the sentence strip. Also exports `buildMergedBoard` for combining base vocabulary with custom pictograms.
vocabulario	`features/vocabulario/`	Vocabulary definitions (`Vocabulary`, `VocabularyData`), the pictogram asset catalog, and hooks for custom pictograms (`useCustomPictograms`), pictogram history (`usePictogramHistory`), disabled pictograms (`useDisabledPictograms`), sentence history (`useSentenceHistory`), guided activities (`useActivities`), AI Magic Expand (`useMagicExpand`), AI adaptation (`useAIAdaptation`), and the child team (`useChildTeam`). The central source of truth for all pictogram content.
ejercicios	`features/ejercicios/`	Exercise definitions and data for G2 and G3 levels. Provides hooks for tracking per-exercise completion state and session progress, consumed by the nested exercise routes.
perfil	`features/perfil/`	Hooks for session reporting (`useReport`), usage statistics (`useStats`), and daily routine tracking (`useRutinas`). Feeds data to the `report.tsx` screen and the `perfil.tsx` tab.
tutorial	`features/tutorial/`	Tutorial step state (`useTutorialState`, `useTutorialBasicState`), voice asset loaders for G1/G2 and G3 audio clips, tutorial script data, and celebration asset helpers. Drives the guided first-run tutorial experience.

ComuniTEA uses Expo Router file-based routing. The route hierarchy has two levels: a root Stack navigator that handles auth-gated screens, and a nested Tabs navigator for the main app experience.

Root Stack (`app/_layout.tsx`)

The root layout wraps the entire app in all React Context providers (in order from outermost to innermost: NetworkProvider → AppThemeProvider → AuthProvider → ChildProfileProvider → EditModeProvider → TimerProvider → ParentalProvider) and then renders a <Stack> with headerShown: false. The auth guard effect runs on every navigation event:

Unauthenticated users visiting any protected route are redirected to /login.
Authenticated users with no voice preference are sent to /voice-selection.
Users who have not completed onboarding are sent to /onboarding.
Users who have not finished the tutorial for their level are sent to /tutorial.
All other authenticated users land in the main tabs at /(tabs)/categorias.

Stack Screen	Route	Purpose
`index`	`/`	Splash/entry redirect
`login`	`/login`	Email + password authentication
`voice-selection`	`/voice-selection`	First-run neural voice picker
`(tabs)`	`/(tabs)/`	Main tab navigator (see below)
`onboarding`	`/onboarding`	Child profile creation wizard
`tutorial`	`/tutorial`	Interactive guided tutorial
`settings`	`/settings`	App settings (parental gate)
`ejercicios`	`/ejercicios`	Nested exercise navigator
`category/[id]`	`/category/:id`	Dynamic sub-category pictogram grid
`sentences`	`/sentences`	Saved sentence history
`report`	`/report`	Session report for caregivers
`vocabulary-manager`	`/vocabulary-manager`	Custom pictogram CRUD
`activity-editor`	`/activity-editor`	Create / edit guided activities
`activity-run`	`/activity-run`	Run a guided activity
`game`	`/game`	Gamified pictogram matching mode
`team-manager`	`/team-manager`	Multi-role caregiver/therapist team

Tabs Navigator (`app/(tabs)/_layout.tsx`)

The tabs layout uses @react-navigation/bottom-tabs via Expo Router’s <Tabs> component. The active tint colour, tab bar background, and indicator dot colour are all driven by useTableroTheme() — a hook that reads from appThemeStore so the palette is consistent with the user’s chosen accent theme.

Tab	Screen	Label
Tablero	`(tabs)/tablero`	Tablero
Ejercicios	`(tabs)/ejercicios`	Ejercicios
Perfil	`(tabs)/perfil`	Perfil

(tabs)/index and (tabs)/categorias are registered as screens but have href: null, meaning they are accessible programmatically but do not appear as visible tab bar items. categorias is the default initial route in the tab navigator.

State Management

ComuniTEA uses Zustand for all global client-side state that must survive across screen navigations and needs optional persistence to AsyncStorage. Each store is focused on a single concern and accessed via a dedicated hook.

Store	File	Responsibility
`useSettingsStore`	`stores/settingsStore.ts`	Persists the user’s voice profile selection (`femenina` \| `masculina`). Reads/writes to `AsyncStorage` via a legacy-compatible adapter.
`useVocabularySentenceStore`	`stores/vocabularySentenceStore.ts`	Holds the in-flight sentence strip state: the ordered array of `VocabularyItem` objects the child has tapped. Provides `addToSentence`, `removeFromSentence`, and `clearSentence` actions.
`useG2ProgressStore`	`stores/g2ProgressStore.ts`	Tracks G2 exercise completion state, registered emotional responses, and assistance records across sessions.
`useG3ProgressStore`	`stores/g3ProgressStore.ts`	Tracks G3 exercise and level completion state.
`useRutinasProgressStore`	`stores/rutinasProgressStore.ts`	Tracks daily routine (rutinas) exercise completion state.
`useAppThemeStore`	`stores/appThemeStore.ts`	Persists the selected accent palette (`ThemeColor`). Defaults to `'sage'`. Consumed by `AppThemeProvider` and `useTableroTheme`.

In addition to Zustand stores, heavier stateful concerns are handled by React Context providers mounted in app/_layout.tsx:

AuthContext — Supabase auth session and user profile
ChildProfileContext — Active child profile data and level
EditModeContext — Parental gate lock/unlock state
TimerProvider — Visual timer state (shared across tablero and activity screens)
ParentalContext — PIN-based parental settings gate
NetworkContext — Online/offline connectivity status (powers NetworkBanner)
AppThemeContext — Current resolved theme colours, fed from appThemeStore

Backend: Supabase

The Supabase project (project_id = "comuniteav0") provides four backend services:

Authentication

Email/password auth via @supabase/supabase-js. Sessions are persisted to the device using expo-secure-store through the SecureStoreAdapter in lib/supabase.ts. Token auto-refresh is enabled with a 1-hour JWT expiry.

PostgreSQL Database

The schema is defined across migrations in supabase/migrations/. Core tables include:

usage_stats — session start/end events and pictogram interaction events
child_profiles — child name, birth date, level (G1/G2/G3), and onboarding state
custom_pictograms — user-created pictogram records with Storage references
sentence_log — timestamped sentence strip history with TTL cleanup
parental_settings — PIN hash and sensory configuration per user
game_sublevel_progress — per-child game sub-level state
guided_activities — caregiver-created activity templates and runs

Storage

A Supabase Storage bucket holds custom pictogram images uploaded by caregivers via expo-image-picker. Storage policies are managed in phase0_fix_storage_policies.sql. The vocabulary-manager screen handles uploads and links records to the custom_pictograms table.

Edge Functions

Four Deno-based Edge Functions are deployed under supabase/functions/:

Function	Trigger	What it does
`ai-expand`	G3 tablero “Magic Expand” button	Accepts pictogram label array + vocabulary level + time of day; calls OpenAI to return a natural first-person Spanish sentence adapted to the child’s level (BASICO: 3–6 words, INTERMEDIO: 5–10 words, AVANZADO: up to 15 words)
`ai-insights`	Caregiver report generation	Analyses session usage data and returns AI-generated suggestions for vocabulary gaps and therapeutic focus areas
`elevenlabs-tts`	On-demand TTS synthesis	Calls the ElevenLabs API to synthesise speech for custom utterances not covered by bundled MP3 assets; requires `ELEVENLABS_API_KEY` secret
`delete-user-data`	Account deletion flow	Cascades deletion of all user-owned rows and storage objects in compliance with data privacy requirements

Audio System

ComuniTEA uses a three-tier audio fallback chain:

1. Bundled MP3 assets (assets/audio/)   ← primary, fully offline
        │
        ▼  (if no bundled asset exists)
2. ElevenLabs TTS (elevenlabs-tts edge function)   ← online, neural voice
        │
        ▼  (if ElevenLabs unavailable)
3. expo-speech system TTS   ← always available, device voice

The bundled MP3 library is organised by voice profile and then by vocabulary category:

assets/audio/
├── femenina/
│   ├── comida/         ├── emociones/      ├── jugar/
│   ├── social/         ├── colores/        ├── ropa/
│   ├── higiene/        ├── baño/           ├── dormir/
│   ├── juguetes/       ├── lugar/          ├── personas/
│   ├── numeros/        ├── tiempo/         ├── yo/
│   ├── core/           ├── tablero/        ├── dashboard/
│   ├── avanzado/       ├── mi_dia/         ├── ejercicios/
│   ├── quiero_menu/    └── no_quiero_menu/
└── masculina/
    └── <same category structure>

Tutorial audio is stored separately in assets/audio/tutorial-g1-g2/ and assets/audio/tutorial-g3/ — each with both voice variants. Audio playback throughout the app uses expo-audio configured with playsInSilentMode: true and interruptionMode: 'mixWithOthers' so pictogram sounds play even when the device is muted or other audio is active.

TypeScript Path Aliases

The tsconfig.json defines four path aliases to keep import statements clean across the codebase:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@features/*": ["features/*"],
      "@stores/*":   ["stores/*"],
      "@types/*":    ["types/*"],
      "@lib/*":      ["lib/*"]
    }
  }
}

Tablero Feature

Communication board internals: pictogram grid, sentence strip, voice playback, and AI Magic Expand.

Exercises & Reports

Exercise structure, game mode sub-levels, and caregiver report generation.

Profile & Onboarding

Child profile setup, user group assignment, and the first-run onboarding flow.

Supabase Reference

Database schema tables, storage policies, and Edge Function API contracts.

Get Started

Core Features

Configuration

ComuniTEA App Architecture: Modules and Navigation

Directory Structure

Feature Modules

Navigation

Root Stack (`app/_layout.tsx`)

Tabs Navigator (`app/(tabs)/_layout.tsx`)

State Management

Backend: Supabase

Authentication

PostgreSQL Database

Storage

Edge Functions

Audio System

TypeScript Path Aliases

Tablero Feature

Exercises & Reports

Profile & Onboarding

Supabase Reference

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Documentation Index

​Directory Structure

​Feature Modules

​Navigation

​Root Stack (app/_layout.tsx)

​Tabs Navigator (app/(tabs)/_layout.tsx)

​State Management

​Backend: Supabase

​Authentication

​PostgreSQL Database

​Storage

​Edge Functions

​Audio System

​TypeScript Path Aliases

Tablero Feature

Exercises & Reports

Profile & Onboarding

Supabase Reference

Build docs developers (and LLMs) love

Directory Structure

Feature Modules

Navigation

Root Stack (`app/_layout.tsx`)

Tabs Navigator (`app/(tabs)/_layout.tsx`)

State Management

Backend: Supabase

Authentication

PostgreSQL Database

Storage

Edge Functions

Audio System

TypeScript Path Aliases