跳转至

App Modules and Directory Structures

Developing in Modules is the best engineering approach. It allows you to build, test, and debug specific parts of the system in isolation without breaking the whole app. It also makes it easier to hire freelancers later to work on just one module (e.g., "Fix the PDF export") without giving them access to your core AI logic.

Here is the Modular Architecture Definition for your AI Autobiography/Companion App.

🧱 Module 1: The Sensory Module (Input & Ingestion)

Purpose: The "Ears" of the system. Its only job is to capture high-fidelity data and move it to the cloud.

  • Key Components:
    • Audio Recorder: High-quality AAC/M4A recording logic (Phone & Watch).
    • Upload Manager: Handles background uploads, retries on bad wifi, and file queuing.
    • Transcriber Service: The Cloud Function that triggers Gemini 2.0 Flash to convert Audio -> Text.
  • Input: User Voice (Raw Audio).
  • Output: transcript.txt and metadata.json (Date, Location, Duration) in the Database.
  • Success Metric: "I speak, and 10 seconds later, text appears in Firestore."

🧠 Module 2: The Identity Engine (Memory & Profile)

Purpose: The "Brain" of the system. It organizes raw text into "Who You Are."

  • Key Components:
    • The Fact Sheet (SQL-like): A structured store for height, weight, names, dates (e.g., user.profile.height = "5'9").
    • The Vector Vault (RAG): The embedding pipeline that turns stories into mathematical vectors for "fuzzy search."
    • The Secretary Agent: A background AI process that scans every new transcript to extract facts and update the Profile automatically.
  • Input: Raw Transcripts.
  • Output: Searchable Vector Index & Structured User Profile.
  • Success Metric: "If I ask 'What is my brother's name?', the system finds it instantly."

💬 Module 3: The Companion Core (Interaction)

Purpose: The "Mouth" of the system. Handles the active conversation and listening.

  • Key Components:
    • Chat Interface: The UI for texting/talking to the AI.
    • Prompt Manager: Injects the "Briefing Packet" (Profile + Recent Context) into Gemini before every reply.
    • TTS (Text-to-Speech): Converts AI text back into a warm, human-like voice.
    • Mode Switcher: Logic to toggle between "Venting Mode," "Advice Mode," and "Interviewer Mode."
  • Input: User text/audio + Vector Context.
  • Output: AI Voice/Text response.
  • Success Metric: "The AI remembers context from 3 messages ago and responds with empathy."

📊 Module 4: The Analyst (Deep Processing)

Purpose: The "Psychologist/Biographer." It runs in the background (batch processing), not real-time.

  • Key Components:
    • The Codebreaker: Analyzes batches of memories for "Longs/Shorts" (Bio, Psych, Social).
    • Gap Detector: Identifies missing timeline eras or contradictory stories.
    • Report Generator: Creates the "Weekly Insight" or "Sunday Review" dashboards.
  • Input: Last 7 days of transcripts.
  • Output: Insight Cards (e.g., "You seem anxious about money") & Critical Questions.
  • Success Metric: "The system highlights a pattern I didn't notice myself."

🗺️ Module 5: The Visualizer (UI & Timeline)

Purpose: The "Display." Visualizing the user's life data.

  • Key Components:
    • Timeline View: Vertical scrolling list of memories (for Adults).
    • World Map: The Gamified Planet view (for Kids).
    • Gap UI: Visual representation of "The Fog" or missing years.
    • Search UI: Interface to query the Vector Database ("Show me all memories about 'Food'").
  • Input: Structured Memory Data.
  • Output: Rendered Flutter Widgets.
  • Success Metric: "I can scroll through my life and clearly see where the holes are."

📚 Module 6: The Publisher (Export & Synthesis)

Purpose: The "Printer." Turning data into a product.

  • Key Components:
    • The Prism Engine: The style transfer logic (Thesis, Tone, Voice) for rewriting text.
    • Chapter Generator: AI logic to weave 50 independent clips into one cohesive narrative.
    • PDF/EPUB Renderer: Formats the text into a book layout with a Table of Contents.
  • Input: Selected Era of Memories.
  • Output: A downloadable PDF/Book file.
  • Success Metric: "The generated chapter reads like a novel, not a police report."

⌚ Module 7: The Bridge (Wearable)

Purpose: The "Satellite." Extending input to the Apple Watch.

  • Key Components:
    • WatchOS App: Simple UI (Record/Stop).
    • Connectivity Layer: WCSession logic to transfer files to the Phone.
    • Notification Handler: Displaying "Critical Questions" on the wrist.
  • Input: Wrist Audio.
  • Output: File transfer to Module 1 (Sensory Module).
  • Success Metric: "I can record on a run without my phone, and it syncs when I get home."

If you are building this solo or with a small team, build the modules in this exact order to maintain a working product at every stage.

  1. Phase 1 (The Recorder): Build Module 1 + Module 5 (Basic List).
    • Result: A voice recorder that transcribes to a list. (Utility App).
  2. Phase 2 (The Memory): Build Module 2.
    • Result: Now you can search your recordings. (Searchable Diary).
  3. Phase 3 (The Companion): Build Module 3.
    • Result: Now the app talks back. (AI Friend).
  4. Phase 4 (The Bridge): Build Module 7.
    • Result: Hands-free experience. (Wearable AI).
  5. Phase 5 (The Analyst): Build Module 4.
    • Result: It gives life advice. (Therapy/Coach App).
  6. Phase 6 (The Book): Build Module 6.
    • Result: It generates the autobiography. (Legacy App).

This modular approach ensures that even if you stop after Phase 3, you still have a valuable, shippable product.

This folder structure is designed for Scalability and Separation of Concerns. It follows a "Feature-First" architecture (rather than Layer-First), meaning every Module we defined has its own dedicated folder containing its specific Logic, UI, and Data code.

This structure allows you to work on "The Recorder" (Sensory) without accidentally breaking "The Book Generator" (Publisher).

📂 Root Project Directory

/autobio_app
├── /android             # Native Android code
├── /ios                 # Native iOS code (Includes WatchOS Target)
├── /lib                 # Flutter Client Code (The App)
├── /functions           # Firebase Cloud Functions (The Backend Brain)
├── /assets              # Images, Fonts, JSON config
├── pubspec.yaml         # Dart Dependencies
└── firebase.json        # Firebase Config

📱 1. The Flutter Client (/lib)

We organize lib by Modules. Each folder here corresponds to the Modules we defined previously.

/lib
├── /core                # Shared utilities used by ALL modules
│   ├── /auth            # Login/Sign-up logic
│   ├── /theme           # Colors, Fonts (The "Prism" styles)
│   ├── /database        # Firestore/Storage generic helpers
│   └── /utils           # Date formatters, UUID generators
│
├── /modules             # THE 7 CORE MODULES
│   │
│   ├── /sensory         # Module 1: Input (Recorder)
│   │   ├── /data        # upload_service.dart, audio_recorder.dart
│   │   ├── /logic       # recorder_bloc.dart (State Management)
│   │   └── /ui          # RecordingScreen.dart, WaveformWidget.dart
│   │
│   ├── /identity        # Module 2: Profile & Memory
│   │   ├── /models      # UserProfile.dart, MemoryModel.dart
│   │   ├── /logic       # profile_cubit.dart, search_bloc.dart
│   │   └── /ui          # ProfileScreen.dart, FactSheetEditor.dart
│   │
│   ├── /companion       # Module 3: Active Listener (Chat)
│   │   ├── /data        # tts_service.dart (Text-to-Speech)
│   │   ├── /logic       # chat_bloc.dart (Handles "Mode Switching")
│   │   └── /ui          # ChatScreen.dart, TypingIndicator.dart
│   │
│   ├── /analyst         # Module 4: Insight Dashboard
│   │   ├── /data        # insight_repository.dart (Fetches reports)
│   │   └── /ui          # WeeklyReportCard.dart, InsightDashboard.dart
│   │
│   ├── /visualizer      # Module 5: Timeline & Maps
│   │   ├── /ui          # TimelineView.dart, GamifiedWorldMap.dart
│   │   └── /widgets     # GapIndicator.dart, FogOfWar.dart
│   │
│   ├── /publisher       # Module 6: Book Generation
│   │   ├── /data        # pdf_service.dart, book_api_client.dart
│   │   └── /ui          # ChapterPreview.dart, StylePicker.dart
│   │
│   └── /bridge          # Module 7: Watch Connectivity
│       ├── /data        # watch_listener_service.dart (MethodChannel)
│       └── /logic       # sync_controller.dart
│
└── main.dart            # App Entry Point

☁️ 2. The Backend (/functions)

The backend logic mirrors the frontend modules. This makes it easy to find where the AI processing happens for each feature.

/functions
├── /src
│   ├── /index.ts           # Main entry point (exports all triggers)
│   │
│   ├── /prompts            # THE AI BRAIN (System Instructions)
│   │   ├── transcription.ts # Prompt for Audio -> JSON
│   │   ├── extraction.ts    # Prompt for "The Secretary" (Facts)
│   │   ├── listener.ts      # Prompt for "The Companion"
│   │   ├── analyst.ts       # Prompt for "Codebreaker/Shorts"
│   │   └── writer.ts        # Prompt for "The Book Generator"
│   │
│   ├── /triggers           # Event Handlers
│   │   ├── on_audio_upload.ts   # (Sensory Module) Triggers Transcription
│   │   ├── on_memory_create.ts  # (Identity Module) Triggers Vector Embedding
│   │   └── on_scheduled_job.ts  # (Analyst Module) Weekly Review
│   │
│   └── /callables          # HTTP Functions called by App
│       ├── generate_question.ts # (Companion) "Shake to Ask"
│       └── generate_chapter.ts  # (Publisher) "Write Book"
│
├── package.json
└── tsconfig.json

⌚ 3. The Native iOS/Watch Structure (/ios)

This is where the WatchOS specific code lives. You won't see this in VS Code's Flutter view easily; you usually edit this in Xcode.

/ios
├── /Runner                 # The iPhone Native Code
│   ├── Info.plist          # Permissions (Mic, Background Audio)
│   ├── AppDelegate.swift   # BRIDGE LOGIC (Receives file from Watch)
│   └── ...
│
├── /WatchApp               # THE WATCH TARGET (New Folder)
│   ├── Interface.storyboard
│   ├── ExtensionDelegate.swift
│   ├── /Audio              # Watch Recorder Logic (Swift)
│   │   └── AudioRecorder.swift
│   ├── /Connectivity       # Watch Sender Logic (Swift)
│   │   └── SessionManager.swift
│   └── /UI                 # SwiftUI Views
│       ├── RecordButtonView.swift
│       └── QuestionCardView.swift
│
├── Podfile                 # iOS Dependencies
└── Runner.xcworkspace      # Open THIS file in Xcode

📝 Practical Tips for Working with This Structure

  1. Strict Rule: A module should rarely talk to another module's internal code.

    • Bad: Sensory module importing a widget directly from Publisher.
    • Good: Sensory saves data to the Database. Publisher reads from the Database. The Database is the decoupling point.

  2. Shared Logic: If code is needed by two modules (e.g., the User data model is needed by everyone), put it in lib/core or lib/modules/identity/models and export it publicly.

  3. Testing: This structure allows you to test lib/modules/sensory without needing the AI or the Chat features working. You can just check "Does it record? Does it upload?"

  4. The "Prompts" Folder: Keep all your Gemini System Instructions in functions/src/prompts. Never hardcode prompts in the Flutter app. This allows you to tweak the AI's personality on the server without forcing users to update their app via the App Store.