# rickmelendez/kleenbelly architecture

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

- Interactive diagram: https://gitdiagram.com/rickmelendez/kleenbelly
- Repository: https://github.com/rickmelendez/kleenbelly

## Overview

KleenBelly is a Flutter calorie-tracking app backed by FastAPI microservices. The main user workflow is to search or create foods, log meals and activity, then view nutrition summaries; profile management and AI-assisted logging/coaching are additional capabilities. The gateway authenticates and proxies requests, while services own their domain logic and persist through Supabase. Mobile implementation files and some gateway/service internals are absent from the supplied tree or excerpts, so their detailed wiring is not inferred.

Main entry points: [`backend/api-gateway/main.py`](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/api-gateway/main.py) (API gateway), [`backend/ai-service/src/application/use_cases`](https://github.com/rickmelendez/kleenbelly/tree/develop/backend/ai-service/src/application/use_cases) (AI use cases), [`backend/nutrition-service/src/presentation/routes/nutrition_routes.py`](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/nutrition-service/src/presentation/routes/nutrition_routes.py) (Nutrition routes), [`backend/user-service/src/presentation/routes/user_routes.py`](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/user-service/src/presentation/routes/user_routes.py) (Profile routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile client"]
  node_mobile["Flutter app"]
end

subgraph group_edge["API edge"]
  node_gateway["API gateway<br/>[main.py]"]
  node_auth["Auth middleware<br/>[auth_middleware.py]"]
end

subgraph group_domains["Domain services"]
  node_user_routes["Profile routes<br/>[user_routes.py]"]
  node_user_usecases["Profile use cases"]
  node_user_repo["User repository"]
  node_food_routes["Food routes<br/>[food_routes.py]"]
  node_food_usecases["Food use cases"]
  node_food_repo["Food repository"]
  node_off["Open Food Facts"]
  node_nutrition_routes["Nutrition routes"]
  node_nutrition_cases["Nutrition use cases"]
  node_meal_repo["Meal repository"]
  node_ai_routes["AI routes<br/>[ai_routes.py]"]
  node_ai_cases["AI use cases"]
end

subgraph group_data["Persistence"]
  node_supabase[("Supabase<br/>[supabase_client.py]")]
  node_auth_service["Supabase Auth"]
end

subgraph group_ai["AI integrations"]
  node_nutrition_tools["Nutrition tools<br/>[nutrition_tools.py]"]
  node_claude["Claude API<br/>[claude_client.py]"]
  node_speech["Speech APIs"]
end

node_person(("App user"))

node_person -->|"uses"| node_mobile
node_mobile -->|"sends HTTP"| node_gateway
node_gateway -->|"validates requests"| node_auth
node_gateway -->|"proxies profile"| node_user_routes
node_gateway -->|"proxies food"| node_food_routes
node_gateway -->|"proxies nutrition"| node_nutrition_routes
node_gateway -->|"proxies AI"| node_ai_routes
node_user_routes -->|"invokes"| node_user_usecases
node_user_routes -->|"deletes account"| node_user_repo
node_user_usecases -->|"reads/writes"| node_user_repo
node_food_routes -->|"invokes"| node_food_usecases
node_food_usecases -->|"searches/stores"| node_food_repo
node_food_repo -->|"reads/writes"| node_supabase
node_food_repo -.->|"looks up foods"| node_off
node_food_routes -->|"uses user identity"| node_auth
node_nutrition_routes -->|"invokes"| node_nutrition_cases
node_nutrition_routes -->|"reads/writes"| node_meal_repo
node_nutrition_cases -->|"reads/writes"| node_meal_repo
node_meal_repo -->|"reads/writes"| node_supabase
node_ai_routes -->|"invokes"| node_ai_cases
node_ai_cases -->|"requests completions"| node_claude
node_ai_cases -->|"transcribes audio"| node_speech
node_ai_cases -->|"uses agent tools"| node_nutrition_tools
node_nutrition_tools -->|"calls nutrition API"| node_nutrition_routes
node_auth -->|"validates JWT"| node_auth_service

click node_mobile "https://github.com/rickmelendez/kleenbelly/tree/develop/mobile/kleenbelly_app"
click node_gateway "https://github.com/rickmelendez/kleenbelly/blob/develop/backend/api-gateway/main.py"
click node_auth "https://github.com/rickmelendez/kleenbelly/blob/develop/backend/shared/middleware/auth_middleware.py"
click node_user_routes "https://github.com/rickmelendez/kleenbelly/blob/develop/backend/user-service/src/presentation/routes/user_routes.py"
click node_user_usecases "https://github.com/rickmelendez/kleenbelly/tree/develop/backend/user-service/src/application/use_cases"
click node_user_repo "https://github.com/rickmelendez/kleenbelly/blob/develop/backend/user-service/src/infrastructure/repositories/supabase_user_repository.py"
click node_food_routes "https://github.com/rickmelendez/kleenbelly/blob/develop/backend/food-service/src/presentation/routes/food_routes.py"
click node_food_usecases "https://github.com/rickmelendez/kleenbelly/tree/develop/backend/food-service/src/application/use_cases"
click node_food_repo "https://github.com/rickmelendez/kleenbelly/blob/develop/backend/food-service/src/infrastructure/repositories/supabase_food_repository.py"
click node_off "https://github.com/rickmelendez/kleenbelly/blob/develop/backend/food-service/src/infrastructure/open_food_facts_client.py"
click node_nutrition_routes "https://github.com/rickmelendez/kleenbelly/blob/develop/backend/nutrition-service/src/presentation/routes/nutrition_routes.py"
click node_nutrition_cases "https://github.com/rickmelendez/kleenbelly/tree/develop/backend/nutrition-service/src/application/use_cases"
click node_meal_repo "https://github.com/rickmelendez/kleenbelly/blob/develop/backend/nutrition-service/src/infrastructure/repositories/supabase_meal_repository.py"
click node_ai_routes "https://github.com/rickmelendez/kleenbelly/blob/develop/backend/ai-service/src/presentation/routes/ai_routes.py"
click node_ai_cases "https://github.com/rickmelendez/kleenbelly/tree/develop/backend/ai-service/src/application/use_cases"
click node_nutrition_tools "https://github.com/rickmelendez/kleenbelly/blob/develop/backend/ai-service/src/infrastructure/nutrition_tools.py"
click node_claude "https://github.com/rickmelendez/kleenbelly/blob/develop/backend/ai-service/src/infrastructure/claude_client.py"
click node_speech "https://github.com/rickmelendez/kleenbelly/blob/develop/backend/ai-service/src/infrastructure/fish_audio_client.py"
click node_supabase "https://github.com/rickmelendez/kleenbelly/blob/develop/backend/shared/database/supabase_client.py"

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_mobile,node_person toneBlue
class node_gateway,node_auth toneAmber
class node_user_routes,node_user_usecases,node_user_repo,node_food_routes,node_food_usecases,node_food_repo,node_off,node_nutrition_routes,node_nutrition_cases,node_meal_repo,node_ai_routes,node_ai_cases toneMint
class node_supabase,node_auth_service toneRose
class node_nutrition_tools,node_claude,node_speech toneIndigo
```

## Components

### Mobile client

- [Flutter app](https://github.com/rickmelendez/kleenbelly/tree/develop/mobile/kleenbelly_app): `mobile/kleenbelly_app`

### API edge

- [API gateway](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/api-gateway/main.py): `backend/api-gateway/main.py`
- [Auth middleware](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/shared/middleware/auth_middleware.py): `backend/shared/middleware/auth_middleware.py`

### Domain services

- [Profile routes](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/user-service/src/presentation/routes/user_routes.py): `backend/user-service/src/presentation/routes/user_routes.py`
- [Profile use cases](https://github.com/rickmelendez/kleenbelly/tree/develop/backend/user-service/src/application/use_cases): `backend/user-service/src/application/use_cases`
- [User repository](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/user-service/src/infrastructure/repositories/supabase_user_repository.py): `backend/user-service/src/infrastructure/repositories/supabase_user_repository.py`
- [Food routes](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/food-service/src/presentation/routes/food_routes.py): `backend/food-service/src/presentation/routes/food_routes.py`
- [Food use cases](https://github.com/rickmelendez/kleenbelly/tree/develop/backend/food-service/src/application/use_cases): `backend/food-service/src/application/use_cases`
- [Food repository](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/food-service/src/infrastructure/repositories/supabase_food_repository.py): `backend/food-service/src/infrastructure/repositories/supabase_food_repository.py`
- [Open Food Facts](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/food-service/src/infrastructure/open_food_facts_client.py): `backend/food-service/src/infrastructure/open_food_facts_client.py`
- [Nutrition routes](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/nutrition-service/src/presentation/routes/nutrition_routes.py): `backend/nutrition-service/src/presentation/routes/nutrition_routes.py`
- [Nutrition use cases](https://github.com/rickmelendez/kleenbelly/tree/develop/backend/nutrition-service/src/application/use_cases): `backend/nutrition-service/src/application/use_cases`
- [Meal repository](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/nutrition-service/src/infrastructure/repositories/supabase_meal_repository.py): `backend/nutrition-service/src/infrastructure/repositories/supabase_meal_repository.py`
- [AI routes](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/ai-service/src/presentation/routes/ai_routes.py): `backend/ai-service/src/presentation/routes/ai_routes.py`
- [AI use cases](https://github.com/rickmelendez/kleenbelly/tree/develop/backend/ai-service/src/application/use_cases): `backend/ai-service/src/application/use_cases`

### Persistence

- [Supabase](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/shared/database/supabase_client.py): `backend/shared/database/supabase_client.py`
- **Supabase Auth**

### AI integrations

- [Nutrition tools](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/ai-service/src/infrastructure/nutrition_tools.py): `backend/ai-service/src/infrastructure/nutrition_tools.py`
- [Claude API](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/ai-service/src/infrastructure/claude_client.py): `backend/ai-service/src/infrastructure/claude_client.py`
- [Speech APIs](https://github.com/rickmelendez/kleenbelly/blob/develop/backend/ai-service/src/infrastructure/fish_audio_client.py): `backend/ai-service/src/infrastructure/fish_audio_client.py`

### Other components

- **App user**

## Connections

- App user → Flutter app: uses
- Flutter app → API gateway: sends HTTP
- API gateway → Auth middleware: validates requests
- API gateway → Profile routes: proxies profile
- API gateway → Food routes: proxies food
- API gateway → Nutrition routes: proxies nutrition
- API gateway → AI routes: proxies AI
- Profile routes → Profile use cases: invokes
- Profile routes → User repository: deletes account
- Profile use cases → User repository: reads/writes
- Food routes → Food use cases: invokes
- Food use cases → Food repository: searches/stores
- Food repository → Supabase: reads/writes
- Food repository → Open Food Facts: looks up foods
- Food routes → Auth middleware: uses user identity
- Nutrition routes → Nutrition use cases: invokes
- Nutrition routes → Meal repository: reads/writes
- Nutrition use cases → Meal repository: reads/writes
- Meal repository → Supabase: reads/writes
- AI routes → AI use cases: invokes
- AI use cases → Claude API: requests completions
- AI use cases → Speech APIs: transcribes audio
- AI use cases → Nutrition tools: uses agent tools
- Nutrition tools → Nutrition routes: calls nutrition API
- Auth middleware → Supabase Auth: validates JWT