g3/analysis/deps/layers.observed.md

# Observed Layering Structure

**Generated**: 2025-02-02  
**Method**: Derived from crate dependencies and file import patterns

## Crate Layers

Based on dependency direction, the crates form the following layers:

```
Layer 0 (Leaf/Foundation):
┌─────────────────┬─────────────────┬─────────────────────────┬─────────────────┐
│   g3-config     │  g3-execution   │  g3-computer-control    │  g3-providers   │
│  (config mgmt)  │ (code execution)│  (browser/UI control)   │ (LLM providers) │
└─────────────────┴─────────────────┴─────────────────────────┴─────────────────┘
                                    │
                                    ▼
Layer 1 (Core Engine):
┌───────────────────────────────────────────────────────────────────────────────┐
│                               g3-core                                         │
│  (Agent, ToolCall, context management, tool dispatch, streaming)              │
└───────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
Layer 2 (Orchestration):
┌───────────────────────────────────────────────────────────────────────────────┐
│                              g3-planner                                       │
│  (fast-discovery planner, git integration, LLM orchestration)                 │
└───────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
Layer 3 (CLI/Application):
┌───────────────────────────────────────────────────────────────────────────────┐
│                               g3-cli                                          │
│  (interactive mode, autonomous mode, agent mode, commands, UI)                │
└───────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
Layer 4 (Binary Entry):
┌───────────────────────────────────────────────────────────────────────────────┐
│                                 g3                                            │
│  (main binary, minimal - delegates to g3-cli)                                 │
└───────────────────────────────────────────────────────────────────────────────┘

Separate:
┌───────────────────────────────────────────────────────────────────────────────┐
│                               studio                                          │
│  (standalone multi-agent workspace manager, no g3 crate dependencies)         │
└───────────────────────────────────────────────────────────────────────────────┘
```

## Layer Violations

**None detected at crate level.**

All dependencies flow downward (higher layer → lower layer). No upward dependencies exist.

## File-Level Layering Within g3-cli

```
Entry Layer:
  lib.rs (run function, mode dispatch)
      │
      ▼
Mode Layer:
  interactive.rs, autonomous.rs, agent_mode.rs, accumulative.rs
      │
      ▼
Command/Execution Layer:
  commands.rs, task_execution.rs, coach_feedback.rs
      │
      ▼
Utility Layer:
  simple_output.rs, g3_status.rs, display.rs, template.rs,
  ui_writer_impl.rs, streaming_markdown.rs, filter_json.rs,
  metrics.rs, project_files.rs, language_prompts.rs, embedded_agents.rs
      │
      ▼
Data Layer:
  cli_args.rs, project.rs, completion.rs, theme.rs
```

## File-Level Layering Within g3-core

```
Entry Layer:
  lib.rs (Agent struct, stream_completion_with_tools)
      │
      ▼
Orchestration Layer:
  retry.rs, compaction.rs, feedback_extraction.rs
      │
      ▼
Tool Layer:
  tool_dispatch.rs, tool_definitions.rs
  tools/mod.rs → tools/{shell,file_ops,plan,webdriver,research,memory,misc,acd}.rs
  tools/executor.rs
      │
      ▼
Streaming Layer:
  streaming.rs, streaming_parser.rs
      │
      ▼
Context Layer:
  context_window.rs, acd.rs, session.rs, session_continuation.rs
      │
      ▼
Infrastructure Layer:
  paths.rs, utils.rs, error_handling.rs, stats.rs,
  provider_config.rs, provider_registration.rs,
  background_process.rs, pending_research.rs,
  webdriver_session.rs, ui_writer.rs, project.rs, prompts.rs
      │
      ▼
Search Layer:
  code_search/mod.rs, code_search/searcher.rs
```

## File-Level Layering Within g3-providers

```
Entry Layer:
  lib.rs (LLMProvider trait, ProviderRegistry, Message types)
      │
      ▼
Provider Implementations:
  anthropic.rs, openai.rs, gemini.rs, databricks.rs, mock.rs
  embedded/mod.rs → embedded/provider.rs, embedded/adapters/{mod,glm}.rs
      │
      ▼
Utility Layer:
  streaming.rs, oauth.rs
```

## Directionality Confidence

| Layer Boundary | Confidence | Notes |
|----------------|------------|-------|
| g3 → g3-cli | High | Single dependency, clear delegation |
| g3-cli → g3-core | High | Many imports, clear consumer relationship |
| g3-cli → g3-planner | High | Explicit dependency for planning features |
| g3-core → g3-providers | High | Core uses provider abstractions |
| g3-core → g3-config | High | Core reads configuration |
| g3-core → g3-computer-control | High | WebDriver integration |
| g3-core → g3-execution | Medium | Declared but minimal observed usage |
| g3-planner → g3-core | High | Planner uses Agent, error handling |

## Uncertainty

1. **g3-execution usage**: Declared as dependency of g3-core but no `use g3_execution::` statements found in source. May be used transitively or for future features.

2. **studio isolation**: studio has no g3 crate dependencies. It may interact with g3 via filesystem/process boundaries rather than library calls.