# jeet2005/niva architecture

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

- Interactive diagram: https://gitdiagram.com/jeet2005/niva
- Repository: https://github.com/jeet2005/niva

## Overview

NIVA is a local-first Flutter personal-context and planning app. The main user workflow is to enter or review tasks and personal context, receive a deterministic daily plan and reminders, and ask questions through an optional Groq-backed conversation boundary; replanning proposals require app-side validation and confirmation. The README also documents memory correction, relevance, route estimates, calendar/weather boundaries, and privacy/settings screens. Mobile source excerpts were not provided, so mobile connections are shown as unverified; the backend-to-Groq call is visible in its excerpt.

Main entry points: [`apps/mobile/lib/context/context_engine.dart`](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/context/context_engine.dart) (Context engine), [`apps/mobile/lib/planning/planning_engine.dart`](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/planning/planning_engine.dart) (Daily planning), [`apps/mobile/lib/features/home/home_screen.dart`](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/home/home_screen.dart) (Home and today), [`apps/mobile/lib/storage/drift_local_store.dart`](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/storage/drift_local_store.dart) (Local persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile experience"]
  node_app["Flutter app shell<br/>[niva_app.dart]"]
  node_app_state["App state<br/>[app_state.dart]"]
  node_home["Home and today<br/>[home_screen.dart]"]
  node_conversation["Conversation"]
  node_plans_ui["Plan screen<br/>[plan_screen.dart]"]
  node_memory_ui["Memory screen"]
  node_privacy_ui["Privacy settings"]
  node_integrations_ui["Integrations screens"]
  node_context_sim["Context simulator"]
end

subgraph group_planning["Context and planning"]
  node_context["Context engine"]
  node_relevance["Relevance engine"]
  node_planning_engine["Daily planning"]
  node_alarm["Adaptive alarms"]
  node_notifications["Reminder scheduling"]
  node_notification_intel["Notification intelligence"]
end

subgraph group_local["Local data"]
  node_memory["Memory service"]
  node_calendar["Calendar boundary"]
  node_weather["Weather boundary"]
  node_routing["Route services"]
  node_route_memory["Route memory"]
  node_store[("Local persistence")]
  node_models["Domain models"]
end

subgraph group_assistant["Assistant boundary"]
  node_backend["Conversation API<br/>[main.py]"]
end

node_user(("Person"))
node_groq{{"Groq API"}}

node_user -.->|"uses"| node_app
node_app -.->|"manages"| node_app_state
node_app_state -.->|"presents"| node_home
node_user -.->|"asks"| node_conversation
node_user -.->|"reviews"| node_plans_ui
node_user -.->|"corrects memories"| node_memory_ui
node_user -.->|"manages privacy"| node_privacy_ui
node_user -.->|"reviews integrations"| node_integrations_ui
node_user -.->|"simulates context"| node_context_sim
node_home -.->|"uses context"| node_context
node_context -.->|"ranks candidates"| node_relevance
node_home -.->|"requests plan"| node_planning_engine
node_planning_engine -.->|"informs alarms"| node_alarm
node_planning_engine -.->|"schedules reminders"| node_notifications
node_notifications -.->|"checks priority"| node_notification_intel
node_memory_ui -.->|"uses memories"| node_memory
node_context -.->|"reads calendar boundary"| node_calendar
node_context -.->|"reads weather boundary"| node_weather
node_context -.->|"uses route context"| node_routing
node_routing -.->|"uses route profiles"| node_route_memory
node_planning_engine -.->|"persists plans"| node_store
node_memory -.->|"persists memories"| node_store
node_store -.->|"stores records"| node_models
node_conversation -.->|"sends request"| node_backend
node_backend -->|"calls"| node_groq

click node_app "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/app/niva_app.dart"
click node_app_state "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/app/app_state.dart"
click node_home "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/home/home_screen.dart"
click node_conversation "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/conversation/conversation_screen.dart"
click node_plans_ui "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/plans/plan_screen.dart"
click node_memory_ui "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/memories/memories_screen.dart"
click node_privacy_ui "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/privacy/privacy_screen.dart"
click node_integrations_ui "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/integrations/integrations_screen.dart"
click node_context_sim "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/integrations/context_simulator_screen.dart"
click node_context "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/context/context_engine.dart"
click node_relevance "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/context/relevance_engine.dart"
click node_planning_engine "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/planning/planning_engine.dart"
click node_alarm "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/planning/adaptive_alarm_service.dart"
click node_notifications "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/notifications/reminder_scheduler.dart"
click node_notification_intel "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/notifications/notification_intelligence.dart"
click node_memory "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/memory/memory_service.dart"
click node_calendar "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/calendar/calendar_service.dart"
click node_weather "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/weather/weather_service.dart"
click node_routing "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/routing/routing_service.dart"
click node_route_memory "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/routing/route_memory_service.dart"
click node_store "https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/storage/drift_local_store.dart"
click node_models "https://github.com/jeet2005/niva/tree/main/apps/mobile/lib/models"
click node_backend "https://github.com/jeet2005/niva/blob/main/backend/app/main.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_app,node_app_state,node_home,node_conversation,node_plans_ui,node_memory_ui,node_privacy_ui,node_integrations_ui,node_context_sim toneBlue
class node_context,node_relevance,node_planning_engine,node_alarm,node_notifications,node_notification_intel toneAmber
class node_memory,node_calendar,node_weather,node_routing,node_route_memory,node_store,node_models,node_groq toneMint
class node_backend toneRose
class node_user toneIndigo
```

## Components

### Mobile experience

- [Flutter app shell](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/app/niva_app.dart): `apps/mobile/lib/app/niva_app.dart`
- [App state](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/app/app_state.dart): `apps/mobile/lib/app/app_state.dart`
- [Home and today](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/home/home_screen.dart): `apps/mobile/lib/features/home/home_screen.dart`
- [Conversation](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/conversation/conversation_screen.dart): `apps/mobile/lib/features/conversation/conversation_screen.dart`
- [Plan screen](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/plans/plan_screen.dart): `apps/mobile/lib/features/plans/plan_screen.dart`
- [Memory screen](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/memories/memories_screen.dart): `apps/mobile/lib/features/memories/memories_screen.dart`
- [Privacy settings](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/privacy/privacy_screen.dart): `apps/mobile/lib/features/privacy/privacy_screen.dart`
- [Integrations screens](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/integrations/integrations_screen.dart): `apps/mobile/lib/features/integrations/integrations_screen.dart`
- [Context simulator](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/features/integrations/context_simulator_screen.dart): `apps/mobile/lib/features/integrations/context_simulator_screen.dart`

### Context and planning

- [Context engine](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/context/context_engine.dart): `apps/mobile/lib/context/context_engine.dart`
- [Relevance engine](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/context/relevance_engine.dart): `apps/mobile/lib/context/relevance_engine.dart`
- [Daily planning](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/planning/planning_engine.dart): `apps/mobile/lib/planning/planning_engine.dart`
- [Adaptive alarms](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/planning/adaptive_alarm_service.dart): `apps/mobile/lib/planning/adaptive_alarm_service.dart`
- [Reminder scheduling](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/notifications/reminder_scheduler.dart): `apps/mobile/lib/notifications/reminder_scheduler.dart`
- [Notification intelligence](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/notifications/notification_intelligence.dart): `apps/mobile/lib/notifications/notification_intelligence.dart`

### Local data

- [Memory service](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/memory/memory_service.dart): `apps/mobile/lib/memory/memory_service.dart`
- [Calendar boundary](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/calendar/calendar_service.dart): `apps/mobile/lib/calendar/calendar_service.dart`
- [Weather boundary](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/weather/weather_service.dart): `apps/mobile/lib/weather/weather_service.dart`
- [Route services](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/routing/routing_service.dart): `apps/mobile/lib/routing/routing_service.dart`
- [Route memory](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/routing/route_memory_service.dart): `apps/mobile/lib/routing/route_memory_service.dart`
- [Local persistence](https://github.com/jeet2005/niva/blob/main/apps/mobile/lib/storage/drift_local_store.dart): `apps/mobile/lib/storage/drift_local_store.dart`
- [Domain models](https://github.com/jeet2005/niva/tree/main/apps/mobile/lib/models): `apps/mobile/lib/models`

### Assistant boundary

- [Conversation API](https://github.com/jeet2005/niva/blob/main/backend/app/main.py): `backend/app/main.py`

### Other components

- **Person**
- **Groq API**

## Connections

- Person → Flutter app shell: uses
- Flutter app shell → App state: manages
- App state → Home and today: presents
- Person → Conversation: asks
- Person → Plan screen: reviews
- Person → Memory screen: corrects memories
- Person → Privacy settings: manages privacy
- Person → Integrations screens: reviews integrations
- Person → Context simulator: simulates context
- Home and today → Context engine: uses context
- Context engine → Relevance engine: ranks candidates
- Home and today → Daily planning: requests plan
- Daily planning → Adaptive alarms: informs alarms
- Daily planning → Reminder scheduling: schedules reminders
- Reminder scheduling → Notification intelligence: checks priority
- Memory screen → Memory service: uses memories
- Context engine → Calendar boundary: reads calendar boundary
- Context engine → Weather boundary: reads weather boundary
- Context engine → Route services: uses route context
- Route services → Route memory: uses route profiles
- Daily planning → Local persistence: persists plans
- Memory service → Local persistence: persists memories
- Local persistence → Domain models: stores records
- Conversation → Conversation API: sends request
- Conversation API → Groq API: calls (evidence: `backend/app/main.py`)
