This repository was archived by the owner on Jan 29, 2026. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 71
docs: add architecture roadmap #16
Merged
clduab11
merged 1 commit into
main
from
codex/initiate-milestone-based-roadmap-for-gemini-flow
Aug 28, 2025
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,94 @@ | ||||||
| # Gemini-Flow Architecture & Roadmap | ||||||
|
|
||||||
| ## Milestone 1 – Codebase Scanning & Architecture Mapping | ||||||
| - **Entry Point:** `src/index.ts` re-exports CLI, auth, and interactive modules, forming the public API surface【F:src/index.ts†L1-L16】 | ||||||
| - **CLI Components:** `GeminiCLI` wires commander-based commands and pulls in `SimpleAuth`, `SimpleInteractive`, and logging utilities for orchestration【F:src/cli/gemini-cli.ts†L8-L118】 | ||||||
| - **Authentication:** `SimpleAuth` resolves API keys from env/config and offers testing, save, and status helpers【F:src/core/simple-auth.ts†L1-L104】 | ||||||
| - **Interactive Mode:** `SimpleInteractive` manages readline I/O, session history, and welcome flows【F:src/cli/simple-interactive.ts†L1-L118】 | ||||||
| - **Memory Layer:** `SQLiteMemoryManager` abstracts persistent namespaces with a three-tier fallback: `better-sqlite3 → sqlite3 → sql.js` and WAL tuning【F:src/memory/sqlite-manager.ts†L1-L22】【F:src/memory/sqlite-manager.ts†L68-L110】 | ||||||
| - **Protocol Handling:** `A2AProtocolManager` queues and routes JSON‑RPC messages with metrics, validation, and shutdown semantics【F:src/protocols/a2a/core/a2a-protocol-manager.ts†L1-L142】 | ||||||
| - **GitHub A2A PR System:** coordinates multi-agent review strategies and scoring【F:src/core/github-a2a-pr-system.ts†L1-L152】 | ||||||
|
|
||||||
| ```mermaid | ||||||
| graph TD | ||||||
| subgraph CLI | ||||||
| A[GeminiCLI] | ||||||
| B[SimpleInteractive] | ||||||
| end | ||||||
| subgraph Core | ||||||
| C[SimpleAuth] | ||||||
| D[A2AProtocolManager] | ||||||
| E[GitHub PR System] | ||||||
| end | ||||||
| subgraph Memory | ||||||
| F[SQLiteMemoryManager] | ||||||
| end | ||||||
| A -->|auth| C | ||||||
| A -->|interactive| B | ||||||
| D --> F | ||||||
| E --> D | ||||||
| ``` | ||||||
|
|
||||||
| ```mermaid | ||||||
| sequenceDiagram | ||||||
| participant User | ||||||
| participant CLI as GeminiCLI | ||||||
| participant Auth as SimpleAuth | ||||||
| participant Inter as SimpleInteractive | ||||||
| User->>CLI: gemini chat | ||||||
| CLI->>Auth: loadAuth() | ||||||
| Auth-->>CLI: key status | ||||||
| CLI->>Inter: start() | ||||||
| Inter->>Auth: isAuthenticated() | ||||||
| Inter-->>User: interactive session | ||||||
| ``` | ||||||
|
|
||||||
| ## Milestone 2 – Key Modules & Dependencies | ||||||
| - **Node Engine:** `>=18 <=24`【F:package.json†L12-L14】 | ||||||
| - **Test Scripts:** unit, integration, performance, protocol, Google services, live integration【F:package.json†L21-L40】 | ||||||
| - **Dependency Matrix (excerpt):** | ||||||
|
|
||||||
| | Type | Modules | | ||||||
| | --- | --- | | ||||||
| | Prod | axios, eventemitter3, express, redis, pg, ws | | ||||||
| | Dev | jest, eslint(+security plugin), typedoc, rollup | | ||||||
| | Optional | canvas, puppeteer, sharp | | ||||||
|
|
||||||
| - **Key Module Roles:** | ||||||
| - `sqlite-manager.ts`: namespaced persistent storage with normalization utilities and periodic cleanup hooks【F:src/memory/sqlite-manager.ts†L44-L66】 | ||||||
| - `a2a-protocol-manager.ts`: priority queues, retry policies, and transport hooks for agent messaging【F:src/protocols/a2a/core/a2a-protocol-manager.ts†L50-L108】 | ||||||
| - `github-a2a-pr-system.ts`: strategy-driven PR review sessions across specialized agents【F:src/core/github-a2a-pr-system.ts†L88-L152】 | ||||||
|
|
||||||
| ## Milestone 3 – Technical Debt, Security, Risk | ||||||
| - **SQLite Persistence:** WAL pragmas enabled but no concurrent write guards or cross-platform fallback tests. | ||||||
| - **A2A Manager:** lacks input sanitization for payload sizes and graceful shutdown if transports hang. | ||||||
| - **Dependency Audit:** `npm audit` flags 13 vulnerabilities across `braces`, `lodash`, `minimist`, `shelljs`, etc.【685528†L1-L66】 | ||||||
|
||||||
| - **Dependency Audit:** `npm audit` flags 13 vulnerabilities across `braces`, `lodash`, `minimist`, `shelljs`, etc.【685528†L1-L66】 | |
| - **Dependency Audit:** `npm audit` flags 13 vulnerabilities across `braces`, `lodash`, `minimist`, `shelljs`, etc. |
Copilot
AI
Aug 28, 2025
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The reference 【120e9a†L1-L71】 is another unclear internal identifier. Consider linking to actual test output files or removing this cryptic reference for better documentation clarity.
Suggested change
| - **Test Status:** `npm test` → 20 failing suites (protocol translation, auth, agent counts)【120e9a†L1-L71】 | |
| - **Test Status:** `npm test` → 20 failing suites (protocol translation, auth, agent counts) [See: tests/TEST_OUTPUT.md] |
Copilot
AI
Aug 28, 2025
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The same unclear file reference notation is used here. For better readability, use standard markdown links like [agent-definitions.ts](../src/agents/agent-definitions.ts) or a conventional reference format.
Suggested change
| - `AGENT_DEFINITIONS` enumerates 64 agents across 16 categories, extending Claude-flow taxonomy with Google roles【F:src/agents/agent-definitions.ts†L1-L74】 | |
| - `AGENT_DEFINITIONS` enumerates 64 agents across 16 categories, extending Claude-flow taxonomy with Google roles ([agent-definitions.ts](../src/agents/agent-definitions.ts), lines 1–74) |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The file reference notation using 【F:...†L...】 is unclear and non-standard for technical documentation. Consider using standard markdown links or a more conventional reference format that readers can easily understand and follow.