# sebastian-ec-dev/tutor_inteligente architecture

> Architecture diagram of the GitHub repository sebastian-ec-dev/tutor_inteligente, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sebastian-ec-dev/tutor_inteligente
- Repository: https://github.com/sebastian-ec-dev/tutor_inteligente

## Overview

1. **Overall shape**
   - This is a **mobile client-only** app built with **React Native + Expo**.
   - There is **no custom backend service** in the repo; the app talks directly to **Supabase** for auth/data and to **Gemini** for AI tasks.

2. **App entry and routing**
   - `index.ts` boots the Expo app and `App.tsx` is the top-level component.
   - `src/navigation/AppNavigator.tsx` is the main boundary that decides which screen tree the user sees, typically separating **unauthenticated** flow from the **authenticated study assistant** flow.

3. **Authentication boundary**
   - `src/screens/LoginScreen.tsx` handles sign-in / sign-up through **Supabase Auth**.
   - After authentication, the app transitions into the main navigator and all study data becomes scoped to the current user.

4. **Domain model in Supabase**
   - The README defines the core data model stored in PostgreSQL/Supabase:
     - `subjects` for course organization
     - `audios` for uploaded study material, transcript, summary, and metadata
     - `audio_embeddings` for vectorized chunks used in semantic search
   - The data is explicitly user-scoped through `user_id`, and audio records are tied to a `subject_id`.

5. **Audio processing pipeline**
   - `src/screens/AudioScreen.tsx` is the ingestion/analysis surface for study recordings.
   - The flow is: **audio input → Gemini processing → transcript + summary + embeddings → Supabase persistence**.
   - This is the main “write path” of the system and is what turns raw class recordings into searchable study content.

6. **Retrieval-Augmented chatbot pipeline**
   - `src/screens/ChatbotScreen.tsx` is the conversational query surface.
   - The chatbot uses a **RAG-style flow**: it retrieves relevant chunks from Supabase using embeddings, then uses Gemini to compose the answer from that retrieved context.
   - The README’s RPC function `match_audio_embeddings` is the key retrieval boundary: it filters by **user** and **subject**, then performs cosine-similarity search via `pgvector`.

7. **Study browsing and summaries**
   - `src/screens/HomeScreen.tsx` likely acts as the user’s hub for subjects and stored study items.
   - `src/screens/ResumenScreen.tsx` is the read-only view for the generated transcript/summary content associated with an audio entry.
   - Together these screens separate **organization** from **generated knowledge**.

8. **Service layer**
   - `src/lib/supabase.ts` centralizes the Supabase client configuration and is the app’s persistence/auth gateway.
   - `src/lib/gemini.ts` centralizes Gemini API access for generation, transcription, and embeddings.
   - These two files are the main external-service adapters and form the app’s integration layer.

9. **Shared UI and presentation helpers**
   - `src/components/ui/LoadingModal.tsx` provides a shared loading state.
   - `src/components/ui/Colors.ts` centralizes the visual theme.
   - `src/utils/MessageBubble.tsx` and `src/utils/burbujaEscribiendo.tsx` support the chat UI, while `src/utils/formateoTime.ts` formats timestamps.
   - `src/utils/prompt.ts` likely holds the system/instruction prompt used by the chatbot.

10. **Key architectural boundaries**
   - **UI layer:** screens, reusable bubbles, modal, colors.
   - **Navigation layer:** authenticated vs unauthenticated app flow.
   - **Service layer:** Supabase and Gemini clients.
   - **Data layer:** Supabase tables + vector search RPC.
   - **AI boundary:** Gemini generates structured study artifacts and final chatbot answers; Supabase stores and retrieves them.

11. **Technology choices that matter to the architecture**
   - **React Navigation** controls screen flow.
   - **Supabase PostgreSQL + Auth + pgvector** is the persistent system of record.
   - **Gemini** is the AI engine for content generation and semantic representation.
   - **Markdown chat rendering** is part of the presentation layer, making AI responses readable in the chat UI.

Main entry points: [`src/screens/ChatbotScreen.tsx`](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/screens/ChatbotScreen.tsx) (Chatbot), [`src/lib/supabase.ts`](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/lib/supabase.ts) (Supabase), [`src/screens/HomeScreen.tsx`](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/screens/HomeScreen.tsx) (Home), [`src/screens/AudioScreen.tsx`](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/screens/AudioScreen.tsx) (Audio)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_entry["Entry"]
  node_node_index["index.ts<br/>expo bootstrap<br/>[index.ts]"]
  node_node_app["App.tsx<br/>root shell<br/>[App.tsx]"]
end

subgraph group_group_nav["Navigation"]
  node_node_nav["AppNavigator<br/>route gate<br/>[AppNavigator.tsx]"]
end

subgraph group_group_screens["Screens"]
  node_node_login["Login<br/>auth screen<br/>[LoginScreen.tsx]"]
  node_node_home["Home<br/>study hub<br/>[HomeScreen.tsx]"]
  node_node_audio["Audio<br/>ingestion screen<br/>[AudioScreen.tsx]"]
  node_node_chat["Chatbot<br/>rag screen<br/>[ChatbotScreen.tsx]"]
  node_node_resumen["Resumen<br/>detail screen<br/>[ResumenScreen.tsx]"]
end

subgraph group_group_services["Services"]
  node_node_supabase[("Supabase<br/>persistence/auth<br/>[supabase.ts]")]
  node_node_gemini{{"Gemini<br/>ai engine<br/>[gemini.ts]"}}
end

subgraph group_group_ui["Shared UI"]
  node_node_loading["LoadingModal<br/>shared modal<br/>[LoadingModal.tsx]"]
  node_node_colors["Colors<br/>theme tokens<br/>[Colors.ts]"]
end

subgraph group_group_utils["Utilities"]
  node_node_message["MessageBubble<br/>chat ui<br/>[MessageBubble.tsx]"]
  node_node_typing["Typing Bubble<br/>chat ui"]
  node_node_time["Time Format<br/>format helper<br/>[formateoTime.ts]"]
  node_node_prompt["Prompt<br/>instruction text<br/>[prompt.ts]"]
end

node_node_readme["README<br/>data model spec<br/>[README.md]"]

node_node_index -->|"boots"| node_node_app
node_node_app -->|"renders"| node_node_nav
node_node_nav -->|"unauthenticated"| node_node_login
node_node_nav -->|"authenticated"| node_node_home
node_node_login -->|"auth"| node_node_supabase
node_node_home -->|"open"| node_node_audio
node_node_home -->|"open"| node_node_chat
node_node_home -->|"open"| node_node_resumen
node_node_audio -->|"analyze"| node_node_gemini
node_node_audio -->|"store"| node_node_supabase
node_node_chat -->|"retrieve"| node_node_supabase
node_node_chat -->|"answer"| node_node_gemini
node_node_resumen -->|"read"| node_node_supabase
node_node_audio -->|"status"| node_node_loading
node_node_chat -->|"render"| node_node_message
node_node_chat -->|"feedback"| node_node_typing
node_node_chat -->|"guide"| node_node_prompt
node_node_app -->|"theme"| node_node_colors
node_node_readme -.->|"schema"| node_node_supabase
node_node_readme -.->|"ai flow"| node_node_gemini

click node_node_index "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/index.ts"
click node_node_app "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/App.tsx"
click node_node_nav "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/navigation/AppNavigator.tsx"
click node_node_login "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/screens/LoginScreen.tsx"
click node_node_home "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/screens/HomeScreen.tsx"
click node_node_audio "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/screens/AudioScreen.tsx"
click node_node_chat "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/screens/ChatbotScreen.tsx"
click node_node_resumen "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/screens/ResumenScreen.tsx"
click node_node_supabase "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/lib/supabase.ts"
click node_node_gemini "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/lib/gemini.ts"
click node_node_loading "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/components/ui/LoadingModal.tsx"
click node_node_colors "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/components/ui/Colors.ts"
click node_node_message "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/utils/MessageBubble.tsx"
click node_node_typing "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/utils/burbujaEscribiendo.tsx"
click node_node_time "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/utils/formateoTime.ts"
click node_node_prompt "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/utils/prompt.ts"
click node_node_readme "https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/README.md"

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_node_index,node_node_app toneBlue
class node_node_nav toneAmber
class node_node_login,node_node_home,node_node_audio,node_node_chat,node_node_resumen toneMint
class node_node_supabase,node_node_gemini toneRose
class node_node_loading,node_node_colors toneIndigo
class node_node_message,node_node_typing,node_node_time,node_node_prompt toneTeal
class node_node_readme toneNeutral
```

## Components

### Entry

App bootstrapping and root component

- [index.ts](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/index.ts): expo bootstrap · Starts the Expo app entrypoint. · `index.ts`
- [App.tsx](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/App.tsx): root shell · Top-level application component. · `App.tsx`

### Navigation

Screen-flow boundary for auth and main app states

- [AppNavigator](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/navigation/AppNavigator.tsx): route gate · Chooses unauthenticated versus authenticated app flow. · `src/navigation/AppNavigator.tsx`

### Screens

Primary user-facing study flows

- [Login](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/screens/LoginScreen.tsx): auth screen · Handles sign-in and sign-up through Supabase Auth. · `src/screens/LoginScreen.tsx`
- [Home](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/screens/HomeScreen.tsx): study hub · Entry point for subjects and stored study items. · `src/screens/HomeScreen.tsx`
- [Audio](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/screens/AudioScreen.tsx): ingestion screen · Processes recordings into transcript, summary, and embeddings. · `src/screens/AudioScreen.tsx`
- [Chatbot](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/screens/ChatbotScreen.tsx): rag screen · Answers questions using retrieved embeddings and Gemini. · `src/screens/ChatbotScreen.tsx`
- [Resumen](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/screens/ResumenScreen.tsx): detail screen · Displays generated transcript and summary for an audio entry. · `src/screens/ResumenScreen.tsx`

### Services

External integrations and persistence adapters

- [Supabase](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/lib/supabase.ts): persistence/auth · Central client for auth, database access, and vector search. · `src/lib/supabase.ts`
- [Gemini](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/lib/gemini.ts): ai engine · Generates transcripts, summaries, embeddings, and chat answers. · `src/lib/gemini.ts`

### Shared UI

Reusable presentation pieces

- [LoadingModal](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/components/ui/LoadingModal.tsx): shared modal · Shared loading state for async flows. · `src/components/ui/LoadingModal.tsx`
- [Colors](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/components/ui/Colors.ts): theme tokens · Centralized visual palette and UI colors. · `src/components/ui/Colors.ts`

### Utilities

Chat helpers and formatting

- [MessageBubble](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/utils/MessageBubble.tsx): chat ui · Renders chatbot conversation messages. · `src/utils/MessageBubble.tsx`
- [Typing Bubble](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/utils/burbujaEscribiendo.tsx): chat ui · Animated typing indicator for chat responses. · `src/utils/burbujaEscribiendo.tsx`
- [Time Format](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/utils/formateoTime.ts): format helper · Formats timestamps for the UI. · `src/utils/formateoTime.ts`
- [Prompt](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/src/utils/prompt.ts): instruction text · Holds chatbot system or instruction prompt content. · `src/utils/prompt.ts`

### Other components

- [README](https://github.com/sebastian-ec-dev/tutor_inteligente/blob/main/README.md): data model spec · Documents the Supabase schema and retrieval boundary. · `README.md`

## Connections

- index.ts → App.tsx: boots · Expo entry mounts the root app.
- App.tsx → AppNavigator: renders · App delegates screen flow to the navigator.
- AppNavigator → Login: unauthenticated · Shows login flow before user session exists.
- AppNavigator → Home: authenticated · Shows the main study assistant experience after auth.
- Login → Supabase: auth · Uses Supabase Auth for sign-in and sign-up.
- Home → Audio: open · Home leads into recording ingestion and analysis.
- Home → Chatbot: open · Home leads into conversational study assistance.
- Home → Resumen: open · Home leads to generated content detail views.
- Audio → Gemini: analyze · Audio is processed by Gemini into study artifacts.
- Audio → Supabase: store · Persists transcript, summary, embeddings, and metadata.
- Chatbot → Supabase: retrieve · Fetches relevant chunks via vector search and filters.
- Chatbot → Gemini: answer · Gemini composes the final response from retrieved context.
- Resumen → Supabase: read · Loads stored transcript and summary content.
- Audio → LoadingModal: status · Shows progress during upload and processing.
- Chatbot → MessageBubble: render · Chat responses are displayed through message bubbles.
- Chatbot → Typing Bubble: feedback · Typing indicator communicates streaming or waiting states.
- Chatbot → Prompt: guide · Prompt shapes assistant behavior and answer style.
- App.tsx → Colors: theme · Root UI uses shared color tokens.
- README → Supabase: schema · Documents subjects, audios, embeddings, and RPC search boundary.
- README → Gemini: ai flow · Documents the generation pipeline used by the app.
