Aether

A reflective journal that turns conversations into a living map of emotions, patterns, and personal growth.

Overview

Aether is a Flutter application for guided introspection. Users write freely or begin from a structured reflection, then talk with Nyx, an AI presence designed to respond with clarity instead of generic encouragement.

Each conversation can become an Akashic Record: a concise summary containing emotional signals, recurring themes, tags, and a key insight. Over time, the dashboard connects those records into a personal view of progress.

This repository contains the mobile client. Aether's core experience requires the companion Mosarto/aether_api; the app is not functionally complete without it.

Required backend

Aether API is a mandatory runtime dependency. It owns Firebase token verification, Nyx chat generation, RAG retrieval, semantic memory, AI tools, conversation history, prompt generation, and quota enforcement.

Without the API, the app can initialize Firebase and render local/user-scoped Firestore views, but these features will not work:

• Nyx chat and generated follow-ups
• Dream, aura, stoic, and synchronicity tools
• Reflection prompt generation
• API conversation history and deletion
• Semantic profile and memory retrieval
• Server quota synchronization

Use the same Firebase project for both repositories: FlutterFire configures the client, while the API receives a Firebase Admin service account from that project.

Product experience

Area	What it provides
Dashboard	Daily check-in, celestial progress visualization, streak context, recent records, and entry points into reflection.
Nyx chat	Persistent AI conversations with guided starters, contextual follow-ups, quota feedback, and session history.
AI tools	Dream analysis, emotional aura reading, stoic guidance, and synchronicity interpretation.
Akashic archive	Searchable history of generated records with mood, intensity, tags, summary, and key insight.
Themes	Multiple visual atmospheres built around the cyber-minimal ethereal design system.
Account	Anonymous onboarding, email authentication, profile editing, preferences, notifications, and subscription presentation.

Main screens

Screen	Purpose	Source
Home	Personal overview and daily reflection hub	lib/screens/dashboard/
AI tools	Specialized reflective experiences	lib/screens/ai_tools/
History	Conversations and Akashic Records	lib/screens/history/
Settings	Profile, theme, privacy, notifications, and plan	lib/screens/settings/
Reflection chat	Focused conversation with Nyx	lib/screens/chat/
Record detail	Full generated insight and emotional metadata	lib/screens/akashic_detail/

How it works

Reflection or free-form message
            |
            v
      Authenticated API
            |
            v
  Nyx response + RAG context
            |
            +--> conversation history
            +--> emotional metadata
            +--> Akashic Record
            |
            v
  Dashboard, archive, and profile evolution

The app stores user-facing account, settings, tracker, chat, and summary data in Firestore. The backend maintains enriched semantic memory in Qdrant and performs LLM generation through OpenRouter.

Architecture

lib/
├── data/
│   ├── models/          Domain models and serialization
│   ├── providers/       App-wide ChangeNotifier state
│   ├── repositories/    Firestore and API access
│   └── services/        HTTP client and authentication transport
├── screens/             Feature screens and local widgets
├── services/            Firebase Auth and notification infrastructure
├── widgets/             Shared visual components
├── utils/               Theme, haptic, and prompt helpers
├── firebase_options.dart
└── main.dart

State remains intentionally lightweight:

• setState for local interaction state.
• ChangeNotifier singletons for shared app state.
• StreamBuilder for live Firestore data.
• Repository injection for testable data access.

Technology

Technology	Role
Flutter and Dart	Cross-platform application and UI
Firebase Auth	Anonymous and email-based identity
Cloud Firestore	Profiles, preferences, tracker, chat, and summaries
Firebase Cloud Messaging	Push notification delivery
SharedPreferences	Local freemium and preference state
flutter_animate	Staggered transitions and motion
CustomPainter	Orbs, particles, stars, and constellations
phosphoricons_flutter	Consistent icon system
google_fonts	Plus Jakarta Sans, Inter, and Space Grotesk

Getting started

Prerequisites

• Flutter with a Dart SDK compatible with ^3.11.0
• Android Studio or Xcode for device builds
• Firebase CLI and a Firebase project
• FlutterFire CLI
• A running Aether API

1. Start the required API

Clone and configure Mosarto/aether_api first. Follow its Quick start with Docker guide and confirm:

curl http://localhost:8000/health

The app and API must use the same Firebase project so the backend can verify client ID tokens.

2. Clone and install app dependencies

git clone https://github.com/Mosarto/aether.git
cd aether
flutter pub get

3. Configure Firebase

Committed Firebase files contain placeholders and do not connect to a live project.

dart pub global activate flutterfire_cli
firebase login
flutterfire configure

Enable the Firebase products used by the app:

1. Authentication with Anonymous and Email/Password providers.
2. Cloud Firestore.
3. Cloud Messaging when notification support is required.

Deploy the repository rules and indexes:

firebase deploy --only firestore:rules,firestore:indexes

4. Run against the backend

The API URL is injected at build time through AETHER_API_URL.

# Android emulator
flutter run --dart-define=AETHER_API_URL=http://10.0.2.2:8000

# iOS simulator, desktop, or web
flutter run --dart-define=AETHER_API_URL=http://localhost:8000

# Deployed API
flutter run --dart-define=AETHER_API_URL=https://api.example.com

For physical devices, use the development machine's LAN address and ensure the device can reach that port.

Quality checks

flutter analyze
flutter test

The test suite covers models, repositories, chat state, freemium synchronization, tracker behavior, summaries, and paywall navigation using fake_cloud_firestore and Mockito.

Security notes

• Never commit a production .env, service account, keystore, or signing properties.
• Production Firebase configuration should be generated in private CI or a protected development environment.
• Shared reflection writes require a Firebase Auth token with the admin custom claim.
• Android release signing is intentionally not configured in this repository.
• Firebase client identifiers are not server credentials, but production identifiers should still remain outside a public reference checkout.

Project documentation

• Architecture
• Firestore schema
• Design system

License

Released under the MIT License.