# sam-eer12/void_factor architecture

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

- Interactive diagram: https://gitdiagram.com/sam-eer12/void_factor
- Repository: https://github.com/sam-eer12/void_factor

## Overview

Void Factor is a nutrition-tracking app whose central workflow is meal photo or manual entry, nutrition logging, and daily intake review alongside activity; it also tracks weight and provides model-worded recommendations. Photo analysis passes through an authenticated FastAPI service to a selected vision provider, while recommendations run on-device. The graph preserves the documented profile, health, export/import, reminder, and support capabilities. Flutter source files are not present in the supplied tree, so those nodes use paths explicitly documented in the README; their connections are documented rather than source-verified.

Main entry points: [`microservice/app/routes.py`](https://github.com/sam-eer12/void_factor/blob/main/microservice/app/routes.py) (Analysis routes), [`lib/screens`](https://github.com/sam-eer12/void_factor/tree/main/lib/screens) (Meal logging), [`microservice/app/providers/openai_compatible.py`](https://github.com/sam-eer12/void_factor/blob/main/microservice/app/providers/openai_compatible.py) (OpenAI-compatible client), [`lib/features/projection`](https://github.com/sam-eer12/void_factor/tree/main/lib/features/projection) (Trajectory engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile tracking"]
  node_auth["Sign-in"]
  node_food_ui["Meal logging"]
  node_food_store[("Food log")]
  node_profile[("Profile")]
  node_health["Activity tracking"]
  node_weight[("Weight log")]
  node_ios_health["HealthKit observer"]
end

subgraph group_personal["Personal insights"]
  node_projection["Trajectory engine"]
  node_gemma["On-device Gemma"]
  node_export["Data transfer"]
  node_reminders["Meal reminders"]
  node_support["Support links"]
end

subgraph group_analysis["Food analysis service"]
  node_api["Analysis routes<br/>[routes.py]"]
  node_verify["Token verification<br/>[auth.py]"]
  node_image["Image validation<br/>[images.py]"]
  node_contract["Analysis contract<br/>[schemas.py]"]
  node_normalize["Response parsing<br/>[parsing.py]"]
  node_app["FastAPI app<br/>[main.py]"]
end

subgraph group_providers["Vision providers"]
  node_gemini["Gemini adapter<br/>[gemini.py]"]
  node_openrouter["OpenRouter adapter<br/>[openrouter.py]"]
  node_openai["OpenAI-compatible client"]
  node_nvidia["NVIDIA adapter<br/>[nvidia.py]"]
  node_provider_services(("Model providers"))
end

subgraph group_delivery["Model delivery"]
  node_model_api["Signed model links<br/>[models.py]"]
  node_android_delivery["Engine installer"]
end

node_user(("App user"))
node_healthkit(("HealthKit"))
node_google_keys(("Google signing keys"))

node_user -.->|"signs in"| node_auth
node_user -.->|"logs meals"| node_food_ui
node_food_ui -.->|"submits photo"| node_api
node_api -->|"verifies caller"| node_verify
node_api -->|"validates upload"| node_image
node_api -->|"dispatches"| node_gemini
node_api -->|"dispatches"| node_openrouter
node_api -->|"dispatches"| node_nvidia
node_gemini -->|"requests analysis"| node_provider_services
node_openrouter -->|"delegates"| node_openai
node_nvidia -->|"delegates"| node_openai
node_openai -->|"requests analysis"| node_provider_services
node_gemini -->|"parses response"| node_normalize
node_openai -->|"parses response"| node_normalize
node_api -->|"validates response"| node_contract
node_api -.->|"returns analysis"| node_food_ui
node_food_ui -.->|"saves entry"| node_food_store
node_user -.->|"logs manually"| node_food_store
node_food_store -.->|"supplies intake"| node_projection
node_weight -.->|"supplies weigh-ins"| node_projection
node_profile -.->|"supplies profile"| node_projection
node_health -.->|"observes changes"| node_ios_health
node_ios_health -->|"observes samples"| node_healthkit
node_projection -.->|"words recommendations"| node_gemma
node_user -.->|"exports or imports"| node_export
node_user -.->|"sets reminder"| node_reminders
node_user -.->|"opens support"| node_support
node_app -->|"registers routes"| node_api
node_app -->|"registers routes"| node_model_api
node_verify -->|"fetches signing keys"| node_google_keys
node_android_delivery -.->|"installs engine"| node_gemma
node_model_api -.->|"provides download link"| node_android_delivery

click node_auth "https://github.com/sam-eer12/void_factor/tree/main/lib/features/auth"
click node_food_ui "https://github.com/sam-eer12/void_factor/tree/main/lib/screens"
click node_food_store "https://github.com/sam-eer12/void_factor/tree/main/lib/features/food_log"
click node_profile "https://github.com/sam-eer12/void_factor/tree/main/lib/features/profile"
click node_health "https://github.com/sam-eer12/void_factor/tree/main/lib/features/health"
click node_weight "https://github.com/sam-eer12/void_factor/tree/main/lib/features/weight_log"
click node_projection "https://github.com/sam-eer12/void_factor/tree/main/lib/features/projection"
click node_gemma "https://github.com/sam-eer12/void_factor/tree/main/android/gemma_engine"
click node_export "https://github.com/sam-eer12/void_factor/tree/main/lib/features/data_transfer"
click node_reminders "https://github.com/sam-eer12/void_factor/tree/main/lib/features/reminders"
click node_support "https://github.com/sam-eer12/void_factor/tree/main/lib/features/support"
click node_api "https://github.com/sam-eer12/void_factor/blob/main/microservice/app/routes.py"
click node_verify "https://github.com/sam-eer12/void_factor/blob/main/microservice/app/auth.py"
click node_image "https://github.com/sam-eer12/void_factor/blob/main/microservice/app/images.py"
click node_contract "https://github.com/sam-eer12/void_factor/blob/main/microservice/app/schemas.py"
click node_normalize "https://github.com/sam-eer12/void_factor/blob/main/microservice/app/parsing.py"
click node_gemini "https://github.com/sam-eer12/void_factor/blob/main/microservice/app/providers/gemini.py"
click node_openrouter "https://github.com/sam-eer12/void_factor/blob/main/microservice/app/providers/openrouter.py"
click node_openai "https://github.com/sam-eer12/void_factor/blob/main/microservice/app/providers/openai_compatible.py"
click node_nvidia "https://github.com/sam-eer12/void_factor/blob/main/microservice/app/providers/nvidia.py"
click node_app "https://github.com/sam-eer12/void_factor/blob/main/microservice/app/main.py"
click node_model_api "https://github.com/sam-eer12/void_factor/blob/main/microservice/app/models.py"
click node_android_delivery "https://github.com/sam-eer12/void_factor/blob/main/android/app/src/main/kotlin/com/voidfactor/app/GemmaEngineDelivery.kt"
click node_ios_health "https://github.com/sam-eer12/void_factor/blob/main/ios/Runner/HealthObserver.swift"

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_auth,node_food_ui,node_food_store,node_profile,node_health,node_weight,node_ios_health,node_user toneBlue
class node_projection,node_gemma,node_export,node_reminders,node_support toneAmber
class node_api,node_verify,node_image,node_contract,node_normalize,node_app toneMint
class node_gemini,node_openrouter,node_openai,node_nvidia,node_provider_services toneRose
class node_model_api,node_android_delivery,node_healthkit,node_google_keys toneIndigo
```

## Components

### Mobile tracking

- [Sign-in](https://github.com/sam-eer12/void_factor/tree/main/lib/features/auth): `lib/features/auth`
- [Meal logging](https://github.com/sam-eer12/void_factor/tree/main/lib/screens): `lib/screens`
- [Food log](https://github.com/sam-eer12/void_factor/tree/main/lib/features/food_log): `lib/features/food_log`
- [Profile](https://github.com/sam-eer12/void_factor/tree/main/lib/features/profile): `lib/features/profile`
- [Activity tracking](https://github.com/sam-eer12/void_factor/tree/main/lib/features/health): `lib/features/health`
- [Weight log](https://github.com/sam-eer12/void_factor/tree/main/lib/features/weight_log): `lib/features/weight_log`
- [HealthKit observer](https://github.com/sam-eer12/void_factor/blob/main/ios/Runner/HealthObserver.swift): `ios/Runner/HealthObserver.swift`

### Personal insights

- [Trajectory engine](https://github.com/sam-eer12/void_factor/tree/main/lib/features/projection): `lib/features/projection`
- [On-device Gemma](https://github.com/sam-eer12/void_factor/tree/main/android/gemma_engine): `android/gemma_engine`
- [Data transfer](https://github.com/sam-eer12/void_factor/tree/main/lib/features/data_transfer): `lib/features/data_transfer`
- [Meal reminders](https://github.com/sam-eer12/void_factor/tree/main/lib/features/reminders): `lib/features/reminders`
- [Support links](https://github.com/sam-eer12/void_factor/tree/main/lib/features/support): `lib/features/support`

### Food analysis service

- [Analysis routes](https://github.com/sam-eer12/void_factor/blob/main/microservice/app/routes.py): `microservice/app/routes.py`
- [Token verification](https://github.com/sam-eer12/void_factor/blob/main/microservice/app/auth.py): `microservice/app/auth.py`
- [Image validation](https://github.com/sam-eer12/void_factor/blob/main/microservice/app/images.py): `microservice/app/images.py`
- [Analysis contract](https://github.com/sam-eer12/void_factor/blob/main/microservice/app/schemas.py): `microservice/app/schemas.py`
- [Response parsing](https://github.com/sam-eer12/void_factor/blob/main/microservice/app/parsing.py): `microservice/app/parsing.py`
- [FastAPI app](https://github.com/sam-eer12/void_factor/blob/main/microservice/app/main.py): `microservice/app/main.py`

### Vision providers

- [Gemini adapter](https://github.com/sam-eer12/void_factor/blob/main/microservice/app/providers/gemini.py): `microservice/app/providers/gemini.py`
- [OpenRouter adapter](https://github.com/sam-eer12/void_factor/blob/main/microservice/app/providers/openrouter.py): `microservice/app/providers/openrouter.py`
- [OpenAI-compatible client](https://github.com/sam-eer12/void_factor/blob/main/microservice/app/providers/openai_compatible.py): `microservice/app/providers/openai_compatible.py`
- [NVIDIA adapter](https://github.com/sam-eer12/void_factor/blob/main/microservice/app/providers/nvidia.py): `microservice/app/providers/nvidia.py`
- **Model providers**

### Model delivery

- [Signed model links](https://github.com/sam-eer12/void_factor/blob/main/microservice/app/models.py): `microservice/app/models.py`
- [Engine installer](https://github.com/sam-eer12/void_factor/blob/main/android/app/src/main/kotlin/com/voidfactor/app/GemmaEngineDelivery.kt): `android/app/src/main/kotlin/com/voidfactor/app/GemmaEngineDelivery.kt`

### Other components

- **App user**
- **HealthKit**
- **Google signing keys**

## Connections

- App user → Sign-in: signs in (evidence: `README.md`)
- App user → Meal logging: logs meals (evidence: `README.md`)
- Meal logging → Analysis routes: submits photo (evidence: `README.md`)
- Analysis routes → Token verification: verifies caller (evidence: `microservice/app/routes.py`)
- Analysis routes → Image validation: validates upload (evidence: `microservice/app/routes.py`)
- Analysis routes → Gemini adapter: dispatches (evidence: `microservice/app/routes.py`)
- Analysis routes → OpenRouter adapter: dispatches (evidence: `microservice/app/routes.py`)
- Analysis routes → NVIDIA adapter: dispatches (evidence: `microservice/app/routes.py`)
- Gemini adapter → Model providers: requests analysis (evidence: `microservice/app/providers/gemini.py`)
- OpenRouter adapter → OpenAI-compatible client: delegates (evidence: `microservice/app/providers/openrouter.py`)
- NVIDIA adapter → OpenAI-compatible client: delegates (evidence: `microservice/app/providers/nvidia.py`)
- OpenAI-compatible client → Model providers: requests analysis (evidence: `microservice/app/providers/openai_compatible.py`)
- Gemini adapter → Response parsing: parses response (evidence: `microservice/app/providers/gemini.py`)
- OpenAI-compatible client → Response parsing: parses response (evidence: `microservice/app/providers/openai_compatible.py`)
- Analysis routes → Analysis contract: validates response (evidence: `microservice/app/routes.py`)
- Analysis routes → Meal logging: returns analysis (evidence: `README.md`)
- Meal logging → Food log: saves entry (evidence: `README.md`)
- App user → Food log: logs manually (evidence: `README.md`)
- Food log → Trajectory engine: supplies intake (evidence: `README.md`)
- Weight log → Trajectory engine: supplies weigh-ins (evidence: `README.md`)
- Profile → Trajectory engine: supplies profile (evidence: `README.md`)
- Activity tracking → HealthKit observer: observes changes (evidence: `README.md`)
- HealthKit observer → HealthKit: observes samples (evidence: `ios/Runner/HealthObserver.swift`)
- Trajectory engine → On-device Gemma: words recommendations (evidence: `README.md`)
- App user → Data transfer: exports or imports (evidence: `README.md`)
- App user → Meal reminders: sets reminder (evidence: `README.md`)
- App user → Support links: opens support (evidence: `README.md`)
- FastAPI app → Analysis routes: registers routes (evidence: `microservice/app/main.py`)
- FastAPI app → Signed model links: registers routes (evidence: `microservice/app/main.py`)
- Token verification → Google signing keys: fetches signing keys (evidence: `microservice/app/auth.py`)
- Engine installer → On-device Gemma: installs engine (evidence: `README.md`)
- Signed model links → Engine installer: provides download link (evidence: `README.md`)