MyGPT Architecture
This document describes the high-level architecture of the MyGPT project using the C4 model.
C1: System Context Diagram
The System Context diagram provides a high-level view of how MyGPT interacts with users and external systems.
C4Context
title System Context diagram for MyGPT
Person(user, "User", "A person who wants to interact with an AI assistant.")
System(mygpt, "MyGPT System", "A personal AI assistant providing autonomous web browsing and chat capabilities.")
System_Ext(ollama, "Ollama", "Local LLM runtime hosted on the user's laptop/server.")
System_Ext(internet, "External Web", "The internet for search results and site content.")
System_Ext(firebase, "Firebase", "Provides Auth and Remote Configuration.")
Rel(user, mygpt, "Interacts with", "Flutter / HTTPS")
Rel(mygpt, ollama, "Requests completions", "Localhost")
Rel(mygpt, internet, "Browses and searches", "HTTP/Playwright")
Rel(mygpt, firebase, "Auth / Config", "HTTPS")
C2: Container Diagram
The Container diagram zooms in on the MyGPT System to show its internal high-level components and how they communicate across the network.
C4Container
title Container diagram for MyGPT
Person(user, "User", "Interacts via Mobile/Desktop")
System_Boundary(c1, "MyGPT System") {
Container(flutter_app, "Flutter Frontend", "Flutter/Dart", "The user interface providing chat and multimodal interactions.")
System_Boundary(local_laptop, "Personal Laptop / Home Server") {
Container(bff, "BFF (Backend-for-Frontend)", "Node.js/Express", "Orchestrates authentication, session management, and data transformation.")
Container(backend, "Agentic Core", "Python/ADK", "The brain of the assistant; manages agents and tool execution.")
ContainerDb(ollama, "Ollama", "Gemma 4", "Local model inference engine.")
Container(lockbox, "Lockbox (Planned)", "TBD", "Secret management and agent policy enforcement (URL/Credential whitelisting).")
}
}
System_Ext(cloudflare, "Cloudflare Tunnel", "Securely bridges the public internet to the local laptop.")
System_Ext(internet, "External Web", "The internet for agents.")
System_Ext(firebase, "Firebase", "Backend-as-a-Service", "Used for Identity Management (Auth) and Remote Config.")
Rel(user, flutter_app, "Uses")
Rel(flutter_app, cloudflare, "Sends requests to", "HTTPS")
Rel(cloudflare, bff, "Routes to local machine", "Tunnel")
Rel(cloudflare, lockbox, "Manage policies & secrets", "Tunnel")
Rel(flutter_app, firebase, "Authenticates & Fetches Config", "Firebase SDK")
Rel(bff, firebase, "Validates Auth Tokens", "Firebase Admin SDK")
Rel(bff, backend, "Commands/Sessions", "ADK Protocol")
Rel(backend, ollama, "Inference", "LiteLLM/Localhost")
Rel(backend, internet, "Searches/Browses", "HTTP/Playwright")
Rel(backend, lockbox, "Requests credentials / Verifies URLs", "Localhost")
C3: Component Diagram (Agentic Core)
This diagram dives into the Agentic Core (Python/ADK) to show how the agents utilize specialized tools and the MCP protocol for secure execution.
C4Component
title Component diagram for Agentic Core
Container(bff, "BFF", "Node.js", "Sends user prompts and manages sessions.")
Container_Boundary(agent_core, "Agentic Core (Python)") {
Component(adk_orchestrator, "ADK Orchestrator", "Google ADK", "Manages agent state, planning, and tool execution loops.")
Component(browser_tool, "Web Browser Tool", "Playwright + Chrome", "Navigates websites, takes screenshots, and interacts with DOM.")
Component(search_tool, "Search Tool", "DuckDuckGo/Python", "Performs quick text-based web searches.")
Component(mcp_client, "MCP Client", "Model Context Protocol", "Exchanges context and policies with Lockbox.")
Component(inference, "Inference Engine", "LiteLLM", "Universal adapter for local model completions.")
}
Container(lockbox, "Lockbox", "MCP Server", "The authority for secrets and whitelisted access.")
ContainerDb(ollama, "Ollama", "Gemma 4", "Local LLM runtime.")
System_Ext(internet, "External Web", "Target websites and search APIs.")
Rel(bff, adk_orchestrator, "Sends Task", "ADK Protocol")
Rel(adk_orchestrator, mcp_client, "Consults Policy", "MCP")
Rel(mcp_client, lockbox, "Query allowed URLs/Secrets", "MCP/JSON-RPC")
Rel(adk_orchestrator, browser_tool, "Execute Browsing", "Function Call")
Rel(browser_tool, internet, "Visits", "HTTPS/Playwright")
Rel(adk_orchestrator, search_tool, "Search Query", "Function Call")
Rel(search_tool, internet, "Queries", "HTTPS")
Rel(adk_orchestrator, inference, "Get Next Action", "LiteLLM API")
Rel(inference, ollama, "Generate completion", "HTTP")
C3: Component Diagram (Frontend to BFF Interaction)
This diagram explains the API Key security flow used to secure the Cloudflare Tunnel between the Flutter App and the local development environment.
C4Component
title Component diagram for Frontend to BFF Interaction
System_Ext(firebase, "Firebase Remote Config", "Securely stores and distributes the backend API Key.")
Container_Boundary(flutter, "Flutter Frontend") {
Component(remote_config_client, "Remote Config Client", "Firebase SDK", "Fetches the latest 'BFF_API_KEY' at startup.")
Component(api_client, "Secure API Client", "Dio/HTTP", "Attaches the API Key to the 'X-API-KEY' header of every request.")
}
System_Ext(cloudflare, "Cloudflare Tunnel", "Public-to-Local Bridge")
Container_Boundary(bff_node, "BFF (Node.js/Express)") {
Component(auth_middleware, "API Key Middleware", "Express Middleware", "Intercepts all requests and validates the provided key.")
Component(api_key_store, "Embedded API Key", "Env/Constants", "Stores the valid static key for the session.")
Component(session_manager, "Session Controller", "Express", "Manages individual ADK sessions and relays them to the Backend.")
}
Rel(remote_config_client, firebase, "Fetches API Key", "HTTPS")
Rel(api_client, remote_config_client, "Reads Key from memory")
Rel(api_client, cloudflare, "Sends Request with 'X-API-KEY'", "HTTPS")
Rel(cloudflare, auth_middleware, "Proxies to local laptop", "Tunnel")
Rel(auth_middleware, api_key_store, "Matches received key")
Rel(auth_middleware, session_manager, "Authorized: Forward request")
Rel_Back(auth_middleware, api_client, "Unauthorized: 401 Error")
Deployment Characteristics
- Privacy-First: All model inference happens on the Personal Laptop via Ollama.
- Secure Access: The Flutter App connects to the local environment via a Cloudflare Tunnel, removing the need for port forwarding or a VPN.
- Identity Management: Firebase Auth is handled on both the client (for login) and the BFF (for session validation).
- Static API Key Gate: A second layer of security using a static key distributed via Firebase Remote Config to ensure only authorized frontend builds can talk to the tunnel.
- Agentic Capability: The Agentic Core can autonomously visit the External Web to fulfill user requests using a real browser (Playwright) or search APIs.
- Planned Security (Lockbox): A future component designed to give the user granular control over what the agents can see and use, providing a "Human-in-the-loop" security gate for secrets and network access via the Model Context Protocol (MCP).