How fathym-deno/reference-architecture works
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.