# ovishkh/cal-ai architecture

> Architecture diagram of the GitHub repository ovishkh/cal-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ovishkh/cal-ai
- Repository: https://github.com/ovishkh/cal-ai

## Overview

Cal AI is a Flutter meal-planning app whose principal workflow is recipe generation from text, images, or voice, followed by nutrition review; users can also create weekly plans and export them. The README documents authentication, profile history, and Firestore persistence as additional capabilities. The Dart implementation was not sampled, so internal call ownership and screen-to-service wiring cannot be verified; dashed, uncited edges mark those unverified relationships.

Main entry points: [`lib/screens/calorie_ai.dart`](https://github.com/ovishkh/cal-ai/blob/main/lib/screens/calorie_ai.dart) (Recipe generation), [`lib/screens/planner.dart`](https://github.com/ovishkh/cal-ai/blob/main/lib/screens/planner.dart) (Weekly planner), [`lib/widgets`](https://github.com/ovishkh/cal-ai/tree/main/lib/widgets) (Recipe and nutrition UI), [`lib/main.dart`](https://github.com/ovishkh/cal-ai/blob/main/lib/main.dart) (Flutter entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_app["Flutter entry<br/>[main.dart]"]
  node_screens["App screens"]
  node_controllers["App controllers"]
  node_recipe_ui["Recipe and nutrition UI"]
end

subgraph group_ai["AI meal features"]
  node_recipe_gen["Recipe generation<br/>[calorie_ai.dart]"]
  node_gemini{{"Gemini API"}}
  node_voice{{"Voice transcription"}}
  node_planner["Weekly planner<br/>[planner.dart]"]
  node_pdf["PDF export"]
end

subgraph group_identity["Identity and records"]
  node_auth_ui["Login and signup<br/>[login.dart]"]
  node_auth_service["Firebase auth service"]
  node_firebase_auth{{"Firebase Authentication"}}
  node_profile["Profile history<br/>[profile.dart]"]
  node_firestore[("Cloud Firestore")]
end

subgraph group_domain["Meal data"]
  node_recipe_model["Recipe model<br/>[recipe.dart]"]
  node_nutrition_model["Nutrition model"]
  node_meal_plan_model["Meal plan model<br/>[meal_plan.dart]"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -.->|"presents"| node_screens
node_screens -.->|"uses"| node_controllers
node_user -->|"requests recipes"| node_recipe_gen
node_recipe_gen -.->|"generates recipes"| node_gemini
node_user -->|"speaks request"| node_voice
node_voice -.->|"transcribes request"| node_recipe_gen
node_recipe_gen -.->|"shows results"| node_recipe_ui
node_recipe_ui -.->|"renders recipe"| node_recipe_model
node_recipe_ui -.->|"visualizes nutrition"| node_nutrition_model
node_user -->|"plans meals"| node_planner
node_planner -.->|"generates plan"| node_gemini
node_planner -.->|"uses plan data"| node_meal_plan_model
node_planner -->|"exports plan"| node_pdf
node_user -->|"signs in"| node_auth_ui
node_auth_ui -.->|"authenticates"| node_auth_service
node_auth_service -.->|"uses"| node_firebase_auth
node_profile -.->|"reads history"| node_firestore
node_recipe_gen -.->|"persists recipes"| node_firestore

click node_app "https://github.com/ovishkh/cal-ai/blob/main/lib/main.dart"
click node_screens "https://github.com/ovishkh/cal-ai/tree/main/lib/screens"
click node_controllers "https://github.com/ovishkh/cal-ai/tree/main/lib/controllers"
click node_recipe_ui "https://github.com/ovishkh/cal-ai/tree/main/lib/widgets"
click node_recipe_gen "https://github.com/ovishkh/cal-ai/blob/main/lib/screens/calorie_ai.dart"
click node_planner "https://github.com/ovishkh/cal-ai/blob/main/lib/screens/planner.dart"
click node_auth_ui "https://github.com/ovishkh/cal-ai/blob/main/lib/screens/login.dart"
click node_auth_service "https://github.com/ovishkh/cal-ai/blob/main/lib/services/firebase_auth_service.dart"
click node_profile "https://github.com/ovishkh/cal-ai/blob/main/lib/screens/profile.dart"
click node_recipe_model "https://github.com/ovishkh/cal-ai/blob/main/lib/models/recipe.dart"
click node_nutrition_model "https://github.com/ovishkh/cal-ai/blob/main/lib/models/nutrition_info.dart"
click node_meal_plan_model "https://github.com/ovishkh/cal-ai/blob/main/lib/models/meal_plan.dart"

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_app,node_screens,node_controllers,node_recipe_ui,node_user toneBlue
class node_recipe_gen,node_gemini,node_voice,node_planner,node_pdf toneAmber
class node_auth_ui,node_auth_service,node_firebase_auth,node_profile,node_firestore toneMint
class node_recipe_model,node_nutrition_model,node_meal_plan_model toneRose
```

## Components

### App experience

- [Flutter entry](https://github.com/ovishkh/cal-ai/blob/main/lib/main.dart): `lib/main.dart`
- [App screens](https://github.com/ovishkh/cal-ai/tree/main/lib/screens): `lib/screens`
- [App controllers](https://github.com/ovishkh/cal-ai/tree/main/lib/controllers): `lib/controllers`
- [Recipe and nutrition UI](https://github.com/ovishkh/cal-ai/tree/main/lib/widgets): `lib/widgets`

### AI meal features

- [Recipe generation](https://github.com/ovishkh/cal-ai/blob/main/lib/screens/calorie_ai.dart): `lib/screens/calorie_ai.dart`
- **Gemini API**
- **Voice transcription**
- [Weekly planner](https://github.com/ovishkh/cal-ai/blob/main/lib/screens/planner.dart): `lib/screens/planner.dart`
- **PDF export**

### Identity and records

- [Login and signup](https://github.com/ovishkh/cal-ai/blob/main/lib/screens/login.dart): `lib/screens/login.dart`
- [Firebase auth service](https://github.com/ovishkh/cal-ai/blob/main/lib/services/firebase_auth_service.dart): `lib/services/firebase_auth_service.dart`
- **Firebase Authentication**
- [Profile history](https://github.com/ovishkh/cal-ai/blob/main/lib/screens/profile.dart): `lib/screens/profile.dart`
- **Cloud Firestore**

### Meal data

- [Recipe model](https://github.com/ovishkh/cal-ai/blob/main/lib/models/recipe.dart): `lib/models/recipe.dart`
- [Nutrition model](https://github.com/ovishkh/cal-ai/blob/main/lib/models/nutrition_info.dart): `lib/models/nutrition_info.dart`
- [Meal plan model](https://github.com/ovishkh/cal-ai/blob/main/lib/models/meal_plan.dart): `lib/models/meal_plan.dart`

### Other components

- **User**

## Connections

- User → Flutter entry: uses (evidence: `README.md`)
- Flutter entry → App screens: presents
- App screens → App controllers: uses
- User → Recipe generation: requests recipes (evidence: `README.md`)
- Recipe generation → Gemini API: generates recipes
- User → Voice transcription: speaks request (evidence: `README.md`)
- Voice transcription → Recipe generation: transcribes request
- Recipe generation → Recipe and nutrition UI: shows results
- Recipe and nutrition UI → Recipe model: renders recipe
- Recipe and nutrition UI → Nutrition model: visualizes nutrition
- User → Weekly planner: plans meals (evidence: `README.md`)
- Weekly planner → Gemini API: generates plan
- Weekly planner → Meal plan model: uses plan data
- Weekly planner → PDF export: exports plan (evidence: `README.md`)
- User → Login and signup: signs in (evidence: `README.md`)
- Login and signup → Firebase auth service: authenticates
- Firebase auth service → Firebase Authentication: uses
- Profile history → Cloud Firestore: reads history
- Recipe generation → Cloud Firestore: persists recipes
