# fathym-deno/reference-architecture architecture

> Architecture diagram of the GitHub repository fathym-deno/reference-architecture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fathym-deno/reference-architecture
- Repository: https://github.com/fathym-deno/reference-architecture

## Overview

##### Project Type and Purpose
- This is an open-source, Deno-based reference architecture library/tool for building command-line interfaces (CLIs) and related utilities.
- It provides a modular “common” CLI framework (parsing, matching, execution, suggestions, scaffolding), build-time scripts (schema emission, versioning), data-store bindings (Deno KV), OAuth helpers, fluent API builders, logging, HTTP utilities, and worker support.

##### File Structure Analysis
- Top-level directories:
- src/build: build tools and Deno config loaders
- src/common: core CLI framework (CLI parser, executor, commands, templates, scaffolding, styling, suggestions)
- src/deno-kv: Deno KV integration
- src/eac, src/fluent, src/log, src/oauth, src/services, src/workers, src/utils: specialized modules
- src/third-party: vendored dependencies (handlebars, zod)
- schemas: JSON Schema definitions for CLI config and metadata
- scripts: standalone scripts to emit schemas, build npm package, runtime glue
- tests: unit tests organized by module
- Build and CI:
- deno.jsonc, .github/workflows/build.yaml define TypeScript compilation, linting, testing

##### Key Insights from README
- Minimal README (“reference-architecture”) suggests the repo itself is a sample or template for CLI architecture.

##### Main Components
a. CLI Framework (runtime):
- CLI Invocation → CLICommandInvocationParser
- CLICommandMatcher/Resolver → CommandModule
- CLICommandExecutor → CommandRuntime
- CLIFileSystemHooks (LocalDev or Embedded)
- TemplateScaffolder + TemplateLocator (DFSTemplateLocator, EmbeddedTemplateLocator)
- CLI suggestions, spinners, styling
b. Build Tools (compile-time):
- scripts/emit-cli-schemas.ts → reads CommandModuleMetadata → writes JSON schemas in /schemas
- scripts/npm.build.ts → packages modules for npm
- src/build (versioning, DenoConfig loader, path resolvers)
c. Data & Services:
- Deno-KV handler (initializeDenoKv, AtomicOperationHandler)
- OAuth helpers (createOAuthConfig, oAuthRequest)
- RealTimeConnection, ObservableContextService, StateContext
d. Utilities & Support:
- LoggingProvider, LineTrackingConsoleHandler
- HTTP utilities (proxyRequest, URLMatch)
- Iterables, tags, merge, path, types modules
e. Third-Party Libraries:
- Handlebars (templating)
- Zod (schema validation)

##### Relationships and Interactions
- Developer runs CLI (ftm-cli) → CLI Framework → uses build tools when emitting templates
- CLI framework and build scripts share metadata (CommandModuleMetadata.schema.json)
- CLI modules call into utilities (path, tags, merge, iterables)
- Runtime modules call Deno-KV and OAuth services for stateful operations
- Tests import core modules and validate CLI behavior, builder patterns, tag utilities

##### Architectural Patterns and Principles
- Modular monorepo with clearly separated concerns
- Dependency injection via context services (ObservableContextService, StateContext)
- Schema-first design (JSON Schemas for config and metadata)
- Fluent builder pattern for domain-specific APIs (EaC, general FluentBuilder)
- Pluggable file system hooks for CLI (LocalDev vs Embedded)
- Template-driven code generation using Handlebars

##### Detailed Steps for the Engineer
3. Off to the side, group TemplateScaffolder + Handlebars → scaffolding output.
7. A Test layer that imports each major module to validate behavior; show it referencing CLI Framework, Utilities, Services.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Outer runtime environment
    subgraph "Deno Runtime" 
        direction TB

        %% CLI Entrypoint
        subgraph "ftm-cli (CLI Entrypoint)"
            direction TB
            Parser["CLICommandInvocationParser"]:::runtime
            Matcher["CLICommandMatcher / CLICommandResolver"]:::runtime
            Executor["CommandRuntime"]:::runtime
            Hooks["CLIFileSystemHooks"]:::runtime
            LocalDevHooks["LocalDevCLIFileSystemHooks"]:::runtime
            Suggestions["CLISuggestions"]:::runtime
            Spinners["Spinners"]:::runtime
            Styling["Styling Utilities"]:::runtime

            Parser -->|invokes| Matcher
            Matcher -->|resolves| Executor
            Executor -->|uses| Hooks
            Hooks -->|supports| LocalDevHooks
            Executor -->|provides| Suggestions
            Executor -->|renders| Spinners
            Executor -->|applies| Styling
        end

        %% Templating
        subgraph "Template Scaffolding"
            direction TB
            Scaffolder["TemplateScaffolder"]:::runtime
            DFSLocator["DFSTemplateLocator"]:::runtime
            EmbeddedLocator["EmbeddedTemplateLocator"]:::runtime
            Scaffolder --> DFSLocator
            Scaffolder --> EmbeddedLocator
        end

        Parser -->|metadata| Scaffolder
    end

    %% Build Tools
    subgraph "Build Tools"
        direction TB
        EmitSchemas["emit-cli-schemas.ts"]:::script
        NPMPack["npm.build.ts"]:::script
        BuildHelpers["src/build tools"]:::build
        EmitSchemas -->|writes schemas| Schemas["/schemas"]
        EmitSchemas -->|uses| BuildHelpers
        NPMPack -->|packages| BuildHelpers
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        HTTP["HTTP Utilities"]:::util
        Iterables["Iterables"]:::util
        Tags["Tags"]:::util
        Merge["Merge"]:::util
        PathUtil["Path Utilities"]:::util
        Types["Types Utilities"]:::util

        HTTP -->|used by| Executor
        Iterables -->|used by| Executor
        Tags -->|used by| Executor
        Merge -->|used by| Executor
        PathUtil -->|used by| BuildHelpers
        Types -->|validates| BuildHelpers
    end

    %% Services
    subgraph "Services & Data"
        direction TB
        KVInit["initializeDenoKv()"]:::service
        AtomicOp["AtomicOperationHandler"]:::service
        KvDB["Deno-KV Store"]:::db
        OAuthCloud["OAuth Providers"]:::external
        OAuthHelpers["OAuthHelpers"]:::service
        OAuthRequest["oAuthRequest"]:::service
        RTC["RealTimeConnection"]:::service
        ObsContext["ObservableContextService"]:::service
        StateCtx["StateContext"]:::service

        KVInit --> KvDB
        AtomicOp --> KvDB
        Executor -->|reads/writes| KVInit
        Executor -->|performs| AtomicOp
        Executor -->|authenticates| OAuthRequest
        OAuthRequest --> OAuthCloud
        Executor -->|configures| OAuthHelpers
        Executor -->|streams| RTC
        Executor -->|injects| ObsContext
        Executor -->|manages| StateCtx
    end

    %% Third-Party
    subgraph "Third-Party Dependencies"
        direction TB
        Handlebars["Handlebars"]:::third
        Zod["Zod"]:::third
        Scaffolder --> Handlebars
        BuildHelpers --> Zod
    end

    %% Click Events
    click Parser "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/cli/CLICommandInvocationParser.ts"
    click Matcher "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/cli/CLICommandMatcher.ts"
    click Matcher "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/cli/CLICommandResolver.ts"
    click Executor "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/cli/commands/CommandRuntime.ts"
    click Hooks "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/cli/CLIFileSystemHooks.ts"
    click LocalDevHooks "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/cli/LocalDevCLIFileSystemHooks.ts"
    click Scaffolder "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/cli/scaffolding/TemplateScaffolder.ts"
    click DFSLocator "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/cli/templates/DFSTemplateLocator.ts"
    click EmbeddedLocator "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/cli/templates/EmbeddedTemplateLocator.ts"
    click Suggestions "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/cli/suggestions/CLISuggestions.ts"
    click Spinners "https://github.com/fathym-deno/reference-architecture/tree/integration/src/common/cli/spinners"
    click Styling "https://github.com/fathym-deno/reference-architecture/tree/integration/src/common/cli/styling"
    click EmitSchemas "https://github.com/fathym-deno/reference-architecture/blob/integration/scripts/emit-cli-schemas.ts"
    click NPMPack "https://github.com/fathym-deno/reference-architecture/blob/integration/scripts/npm.build.ts"
    click BuildHelpers "https://github.com/fathym-deno/reference-architecture/tree/integration/src/build"
    click KVInit "https://github.com/fathym-deno/reference-architecture/blob/integration/src/deno-kv/initializeDenoKv.ts"
    click AtomicOp "https://github.com/fathym-deno/reference-architecture/blob/integration/src/deno-kv/AtomicOperationHandler.ts"
    click OAuthHelpers "https://github.com/fathym-deno/reference-architecture/blob/integration/src/oauth/OAuthHelpers.ts"
    click OAuthRequest "https://github.com/fathym-deno/reference-architecture/blob/integration/src/oauth/oAuthRequest.ts"
    click RTC "https://github.com/fathym-deno/reference-architecture/blob/integration/src/services/RealTimeConnection.ts"
    click ObsContext "https://github.com/fathym-deno/reference-architecture/blob/integration/src/services/ObservableContextService.ts"
    click StateCtx "https://github.com/fathym-deno/reference-architecture/blob/integration/src/services/StateContext.ts"
    click HTTP "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/http/proxyRequest.ts"
    click HTTP "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/http/URLMatch.ts"
    click Iterables "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/iterables/Queue.ts"
    click Iterables "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/iterables/Stack.ts"
    click Tags "https://github.com/fathym-deno/reference-architecture/tree/integration/src/common/tags"
    click Merge "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/merge/merge.ts"
    click PathUtil "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/path/resolvePackageRoot.ts"
    click PathUtil "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/path/exists.ts"
    click Types "https://github.com/fathym-deno/reference-architecture/blob/integration/src/common/types/ValueType.ts"
    click Handlebars "https://github.com/fathym-deno/reference-architecture/tree/integration/src/third-party/handlebars"
    click Zod "https://github.com/fathym-deno/reference-architecture/tree/integration/src/third-party/zod"

    %% Styles
    classDef runtime fill:#D0E8FF,stroke:#005B96,color:#000
    classDef build fill:#E2F0CB,stroke:#6B8E23,color:#000
    classDef script fill:#FDEBD0,stroke:#E67E22,color:#000
    classDef util fill:#FFF2CC,stroke:#D4AC0D,color:#000
    classDef service fill:#FFD1DC,stroke:#C71585,color:#000
    classDef db fill:#D1F2EB,stroke:#1ABC9C,color:#000
    classDef external fill:#F0F0F0,stroke:#7F8C8D,color:#000
    classDef third fill:#E8EAF6,stroke:#5C6BC0,color:#000
```
