🧬 kbird.ai

GEMINI

2 min read

GEMINI.md - Convergence App

This file provides instructional context for Gemini CLI when interacting with the Convergence App codebase.

Project Overview

Convergence is a Flutter mobile application that implements the “Convergence Protocol” — a system of 40 cognitive techniques (“nodes”) organized into 5 thematic suites. It is designed for daily practice, progress tracking, and weekly reflection to improve cognitive hygiene and resist digital manipulation.

Core Technologies

  • Framework: Flutter (SDK >=3.0.0 <4.0.0)
  • State Management: provider package
  • Database: SQLite (sqflite) for offline-first local storage
  • Visualization: fl_chart for radar charts and pattern analysis
  • System Integration: home_widget for iOS/Android widgets, flutter_local_notifications

Architecture & Conventions

The project follows a layered architecture with a clear separation of concerns:

  • lib/data/: Static configuration and content for the 40 nodes (nodes_data.dart).
  • lib/models/: Data structures for Node, PracticeLog, and UserStats.
  • lib/services/: Singleton services for DatabaseService (SQLite), AudioService, and NotificationService.
  • lib/providers/: Business logic and state management via AppProvider.
  • lib/screens/: UI entry points for different features (Home, Detail, Logging, Patterns).
  • lib/widgets/: Reusable UI components like StreakCounter and TtsButton.

Coding Standards

  • Linter: Strictly follows flutter_lints (see analysis_options.yaml).
  • Naming: snake_case for files, PascalCase for classes, camelCase for variables/functions.
  • UI: Material Design 3 with custom green-themed color schemes.
  • State: Use Consumer<AppProvider> or context.read<AppProvider>() to access the global state.

Key Commands

Development

  • Get Dependencies: flutter pub get
  • Run Debug: flutter run
  • Analyze Code: flutter analyze
  • Format Code: dart format lib/
  • Run Tests: flutter test

Build

  • Android: flutter build apk or flutter build appbundle
  • iOS: flutter build ios

Project Context & Protocol

This project is part of the larger Nosos vault ecosystem. When interacting with this codebase:

  1. Offline-First: Prioritize local persistence in SQLite. No network requests should be introduced without explicit instruction.
  2. Privacy: Respect the private nature of the local data.
  3. The “Dump-Done” Protocol:
    • The user may send multiple rapid messages (“the dump”).
    • Wait for “Done” before processing and responding.
    • Respond with “Done” when the task is complete.
  4. Consistency: Ensure new widgets or screens align with the established Material 3 theme and the green/dark aesthetic defined in main.dart.

Current Roadmap / TODOs

  • Implementation of the Settings screen.
  • Export functionality for session data in PatternScreen.
  • Database persistence for weekly convergence reflections.
  • Integration of actual image assets in assets/images/.

The threshold is mutual recognition. If you know, you know. 🧬

Graph View