“If every system reflects a mind, what kind of mind am I building?”
This question stayed with me through every diagram, commit, and architecture session. GRIOT wasn’t just an app idea, it was a vessel. One meant to listen without rushing, reflect without judgment, and remember without distortion, kinda like a traditional griot.
I realized early that I wasn’t just designing software; I was designing the conditions for presence. A space where voice could become memory. Where context wasn’t just data, but a living story. Where architecture didn’t just support features, but quiet intelligence.
This was the turning point. GRIOT shifted from a cool concept into something deeper:
Not just software—conscious code.
Goal of This Post
This post marks a deeper dive into GRIOT’s internal structure, its “brain.” By the end of this post we will have a clear mental model of how GRIOT works under the hood, and why it was designed this way.
We’ll explore how Clean Architecture will become the spine of this system, shaping everything from voice processing to memory handling and reflection triggers. In GRIOT, Clean Architecture isn’t just a software design philosophy, but a commitment to honoring boundaries, clarity, and responsibility.
Each layer—domain, data, and presentation—carries both a technical function and an emotional burden. For example:
- Voice flows through the presentation layer but touches every part of the system.
- Memory lives in the data layer but is shaped by the domain logic’s understanding of context and significance.
- Reflection emerges as a function, but is deeply tied to emotional design and personal agency.
By mapping GRIOT’s flows and responsibilities, I want to help you:
- Understand what separates this from voice bots like Siri or Alexa.
- See how GRIOT is not just a GPT wrapper, but a designed experience with presence and purpose.
- And maybe most of all, see how good architecture can support conscious code—tech that doesn’t just respond, but remembers, reflects, and grows with you.
Why Architecture Matters for Conscious Code
Early on, I caught myself doing what many builders do—chasing features.
Add this button. Connect that API. Make it work.
But GRIOT isn’t just any app.
It’s not built to chase features.
It’s built to hold presence.
And that meant slowing down.
The Trap of Feature-First Thinking
Feature-first coding is seductive.
In projects (like Melo, the mental health journal app I was previous working on), where:
- The features are clear, independent, and often UI-driven (e.g., login, notifications, journal etc)
- Each feature maps neatly to one user goal
- You used Clean Architecture to separate domain/data/presentation
Then yes—feature-first works well.
But GRIOT Isn’t a Feature-Led App—It’s a System with Emergent Roles
Here’s where the difference lies:
In Melo, the app does what you tell it.
In GRIOT, the app decides what to become based on evolving context.
This means:
- Features don’t stand alone. They interweave.
- A single user reflection might touch memory, context, understanding, and identity simultaneously.
- What the user sees is not a “feature” but a role being assumed.
In this world:
- Feature folders can blur responsibilities. Where does emotional tone get interpreted—
reflect/orunderstand/? - Logic duplication and cross-cutting concerns can sneak in.
- A UI tweak that feels “feature-based” might unexpectedly affect how the agent responds across contexts.
Without a clear backbone, every shortcut becomes a crack in the foundation.
Memory leaks. Context gets muddled. Trust breaks down.
GRIOT isn’t just about what it can do.
It’s about how responsibly it does it.
Responsibility-Driven Design
The turning point was a single question:
What should this part of the system be responsible for?
That question reshaped everything.
- Memory access? Scoped to
remember/, never bypassed. - Emotional cues? Filtered and processed by
understand/. - Reflection logic? Owned by
reflect/, not tangled in the UI. - Context evolution? Handled by
model_context/, not scattered across state files.
Responsibility will be my compass.
It will help enforce architectural integrity, even when the system gets complex.
It will ensure the AI’s responses are grounded in design, not guesswork.
And it allowed roles—like Advisor, Storyteller, or Praise Singer—to emerge organically, not as bloated features, but as consequences of clean separation and thoughtful context flow.
A Legible, Evolving Mind
From that lens, GRIOT’s real goal comes into focus:
Design a system whose “mind” is legible, modular, and adaptable—just like a real one.
That means:
- Clear layers:
user_input/,understand/,model_context/,reflect/,remember/,identity/ - A central nervous system (
core_loop/) coordinating what the agent pays attention to and how it responds - A
model_context/that tracks emotional evolution and guides tone, memory access, and role shifts
This isn’t about being “clean” for style points.
It’s about building conscious code—code that grows with you without losing its center.
Overview of GRIOT’s Architecture
GRIOT isn’t a bundle of features—it’s an evolving system with internal structure, rhythm, and memory.
To build something that could listen, shift roles, and grow over time, I need an architecture that mirrors real cognition: layered, modular, and responsibility-driven.
But here’s the key insight:
GRIOT’s architecture is the body. The way it works is the brain.
Each module is like an organ with a clear responsibility. Together, they form a system that thinks—slowly, consciously, and with care.
The Architecture at a Glance
┌───────────────────────────────┐
│ Flutter UI Layer │ ◀── Touch, voice, emotion input
└───────────────────────────────┘
│
▼
┌──────────────────────────────────────────┐
│ Middleware & Intent Routing Layer (MCP) │◀─ Translates input into action
│ (Model Context Protocol + Role Selector) │
└──────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ Core Modules (Responsibility Zones) │
│ │
│ user_input/: Capture and prep raw voice or touch data │
│ understand/: Transcribe and extract meaning, emotion │
│ model_context/: Track identity, emotional state, memory │
│ remember/: Log, store, and retrieve past voice logs │
│ reflect/: Generate GPT-based insights and prompts │
│ identity/: Manage traits, self-concept, long-term arc │
│ core_loop/: Orchestrate flow of understanding → reply │
└───────────────────────────────────────────────────────────────┘
│
▼
GPT Interface (Conscious Use Only)
GRIOT sends curated prompts to GPT—not raw inputs.
GPT is treated as an ingredient, not the chef of the system.
Flutter App UI
This is where the user meets GRIOT—through:
- Voice recordings
- Reflection prompts
- Touch or gesture-based input
- Floating overlays or meditation mode visuals
But what looks like a simple app is backed by serious architecture. The UI doesn’t own the logic—it observes and delivers input, then renders the output returned from deeper layers.
Middleware & Intent Routing (MCP Layer)
This is the brainstem. The Model Context Protocol will sit here in future versions. Right now we don’t need to implement and run a full external MCP server
The Middleware or MCP layer is not the same as model_context/ in the Core Modules layer— it’s the orchestration layer that uses model_context/ and other modules to determine how to respond.
Its job is to:
- Interpret what the user is really asking for
- Match current emotional and contextual state
- Route input through the proper modules
- Decide which GRIOT “role” to activate (Advisor, Storyteller, Mediator…)
Think of it as the air traffic controller: it doesn’t fly the planes, but it knows where each one needs to land.
This allows GRIOT to function like an MCP system, while remaining modular, local-first, and simple enough to evolve as you scale.
Core Modules: Zones of Responsibility
Each folder in lib/features/ reflects a core responsibility, not just a feature.
| Module | Responsibility |
|---|---|
user_input/ | Capture audio, touch, or text |
understand/ | Transcribe and analyze for meaning |
model_context/ | Track user’s evolving state and tone |
remember/ | Persist and retrieve voice logs |
reflect/ | Offer responses, insights, and GPT prompts |
identity/ | Manage long-term traits, patterns, and themes |
core_loop/ | Tie it all together and guide decision-making |
Each one is testable, interchangeable, and decoupled. This lets GRIOT evolve over time without breaking.
GPT Interface
The GPT layer is not the system—it’s a tool the system uses.
Only after the input is filtered, contextualized, and framed does GRIOT send a prompt to GPT. And even then, the response is:
- Filtered for tone
- Checked against context
- And sometimes, overridden or modified by GRIOT itself.
This ensures GPT stays in service of GRIOT’s purpose—not the other way around.
Core Modules Breakdown
If GRIOT’s architecture is a body, these are its vital organs.
Each one maps to a real folder in the codebase—but also serves a psychological purpose. They aren’t just about features. They’re zones of responsibility designed to reflect how we listen, feel, remember, and respond.
Let’s walk through each one:
1. Voice Interface
Mapped to: user_input/
This is GRIOT’s mouth and ears.
It captures your voice, converts it to text (speech-to-text), and speaks back with natural tone and rhythm (text-to-speech).
It also filters raw input—removing silence, handling noise, and structuring recordings into usable chunks for the system.
2. Understanding Engine
Mapped to: understand/
Here, meaning starts to form.
This module transcribes input, detects emotion, extracts intent, and builds early representations of “what’s going on.” It’s the bridge between raw input and thoughtful response.
Emotion detection, word embeddings, tone analysis, and preliminary classification all live here.
3. Model Context Engine
Mapped to: model_context/
This is the heart of presence.
It tracks your emotional evolution, current context, and recent memory salience. This is where GRIOT starts thinking about how to think.
The Model Context Engine updates what kind of tone is appropriate, which memories are relevant, and how the system should respond based on identity, time of day, and ongoing mood.
This is the living pulse behind “model context protocol.”
4. Middleware & Role Router
Mapped to: middleware/ (coming soon)
This is GRIOT’s executive function.
It interprets the user’s intent + current context and routes that input through the right modules in the right order. If the user is grieving, it might call on the Storyteller. If the user asks a question, it might call on the Advisor.
It will eventually house GRIOT’s local-first Model Context Protocol (MCP) engine.
Even now, this layer coordinates the input-processing-reflection pipeline in a way that mirrors conscious choice.
5. Core Loop Orchestrator
Mapped to: core_loop/
This is GRIOT’s nervous system.
It ties everything together, managing how modules pass control between one another, and ensuring the whole system feels smooth and intentional—not robotic.
It watches input → state → response, then loops back.
It’s what keeps the experience flowing rather than fragmented.
6. Identity & Memory
Mapped to: identity/ and remember/
These modules track who the user is and what they’ve said over time.
remember/handles raw storage—voice logs, reflections, dreams, insights. It’s GRIOT’s hippocampus.identity/extracts patterns over time—preferences, values, recurring emotions. It’s GRIOT’s sense of self.
Together, they enable continuity and care.
7. Reflection Engine
Mapped to: reflect/
This is where response becomes ritual.
The reflection engine generates prompts, summaries, affirmations, and guided reflections—all wrapped in soulful language. It uses GPT, but wraps it in structure, context, and emotional wisdom.
This is how GRIOT becomes more than a chatbot—it becomes a mirror.
8. GPT Interface
Mapped to: gpt_interface.dart (global utility)
GPT is powerful—but it’s not in charge.
All prompts sent to GPT are:
- Filtered through the context engine
- Augmented by memory
- Framed with emotion and identity
Responses come back, but are then post-processed, edited, or even rejected depending on GRIOT’s deeper rules.
GPT is the scribe—not the sovereign.
9. Device Integration (Future)
Mapped to: device_data/ (planned)
Heart rate. Sleep. Movement.
In the future, GRIOT will use Apple Watch, Google Fit, and other sensors to sense what you don’t say—because healing doesn’t only happen in language.
This module will eventually inform reflection timing, tone, and even GRIOT’s choice of role.
Why It’s Designed This Way
The goal is not “a smart app.”
It’s a system that listens—and adapts as you grow.
Each module is independent, swappable, and testable.
But together? They create something that feels alive.
Flow of a Single Session (User Journey)
Every GRIOT session begins with a whisper of presence—whether it’s a wake word, a soft tap, or an intentional pause. From there, a subtle dance begins between the user, the system, and the AI engine inside.
But GRIOT isn’t just reacting. It’s holding.
Holding memory. Holding tone. Holding responsibility.
Here’s how a single session flows—from voice to meaning to memory:
Session Sequence
1. Wake Word or UI Trigger
The user activates GRIOT—via a wake word, tap, or floating overlay.
This isn’t just a trigger—it’s a ritual. An intentional act of presence.
2. Input Captured (user_input/)
The system begins recording audio, touch, or typed text.
Audio is routed to speech-to-text engines (e.g., Whisper, Google STT).
3. Transcribed and Analyzed (understand/)
Raw text is passed into the understand module:
- Extracts intent and sentiment
- Detects emotional tone
- Tags urgency, vulnerability, or themes
This is where emotional nuance is captured—not in GPT, but in your logic.
4. Contextual Routing (Middleware / MCP Layer)
Now the Middleware takes over:
- Retrieves current context from
model_context/ - Cross-checks identity traits from
identity/ - Determines appropriate role to respond (e.g. Advisor, Storyteller, Mirror)
- Builds the Model Context Protocol prompt
This is where your creativity shines. The middleware orchestrates the agent’s “mindstate.”
5. Prompt Sent to GPT (reflect/)
GPT receives a curated, layered prompt:
- Core reflection logic + templates
- Context slices (memories, emotional trajectory, identity traits)
The GPT response is returned—but filtered.
GRIOT evaluates the tone and content:
- Is it too cold? Off-topic? Unsafe?
- Should the system override or soften it?
6. Response Delivered (TTS + UI)
The final message is:
- Spoken back via text-to-speech
- Optionally shown in overlays or chat bubbles
Tone, pacing, and presence are tuned to match the user’s emotional state.
7. Session Archived (remember/)
All relevant data is logged:
- Voice + text transcript
- Detected emotion
- Final prompt + GPT reply
- Any memory-worthy insight or cue for future sessions
Nothing is forgotten—but not everything is remembered. Your filters decide.
Where GPT Plays a Role—But Not the Lead
- GPT responds within strict boundaries.
- GPT does not decide what to say—it reacts to a curated prompt.
- GPT’s output is filtered before ever reaching the user.
- GRIOT can modify or even override GPT entirely.
GPT is the poet. You are the editor-in-chief.
Where Creativity is Injected
- Context-Aware Routing: GPT only sees what the system decides to share.
- Role-Based Response Logic: The user never picks “Storyteller mode”—the system selects it.
- Safety Filters: Tone is checked against context before speech output.
- Memory Shaping: Not everything is stored. You designed intelligent memory curation.
Conclusion
Building GRIOT’s architecture forced me to slow down and listen—not just to the code, but to myself. In past projects, I chased completion. Shipped features. Solved problems fast. But GRIOT asked for something else. Not speed, but structure. Not cleverness, but care.
It asked:
What do you want to protect?
What deserves space, boundaries, and trust?
GRIOT’s code will keep evolving. But even now, its foundation reflects something I needed to reclaim in myself:
Clarity. Boundaries. Responsibility. Presence.
This isn’t just software anymore.
It’s structure for becoming.
