Skip to content

Architecture

This document describes the architecture of Fast Craftsmanship, explaining how the components fit together and the design decisions behind them.

Overview

Fast Craftsmanship follows a modular, functional architecture with a clear separation of concerns:

┌─────────────────┐
│    CLI Layer    │
└───────┬─────────┘
        │
┌───────▼─────────┐
│  Command Layer  │
└───────┬─────────┘
        │
┌───────▼─────────┐
│  Domain Layer   │
└───────┬─────────┘
        │
┌───────▼─────────┐
│  Utility Layer  │
└─────────────────┘

Layers

CLI Layer

The CLI layer handles user interaction through the command line interface. It:

  • Parses command-line arguments
  • Dispatches to the appropriate commands
  • Formats output for display
  • Handles command-line flags and options

Key files: - fcship/cli.py: Main entry point and command registration - fcship/tui/: Text UI components for display and interaction

Command Layer

The Command layer contains the implementation of all commands. Each command:

  • Takes validated input from the CLI layer
  • Implements the business logic for the command
  • Returns a Result that may contain data or errors
  • Is responsible for a specific domain of functionality

Key files: - fcship/commands/*.py: Individual command modules - fcship/commands/__init__.py: Command registration and organization

Domain Layer

The domain layer contains the core business logic and models. It:

  • Defines data structures and validation rules
  • Implements domain-specific operations
  • Is independent of the command and CLI layers
  • Uses Railway Oriented Programming for error handling

Key files: - Domain models in various command modules - Validation logic and business rules

Utility Layer

The utility layer provides common functions and tools used across the application:

  • Error handling utilities
  • File system operations
  • Functional programming helpers
  • Type utilities

Key files: - fcship/utils/error_handling.py: Error utilities - fcship/utils/file_utils.py: File system operations - fcship/utils/functional.py: Functional programming utilities - fcship/utils/type_utils.py: Type handling utilities

Key Design Principles

Functional Programming

Fast Craftsmanship is built on functional programming principles:

  • Pure Functions: Functions have no side effects and return the same output for the same input
  • Immutable Data: Data structures are immutable, using Pydantic models
  • Railway Oriented Programming: Error handling using Result types
  • Function Composition: Building complex operations by composing simple functions

Railway Oriented Programming (ROP)

ROP is a core pattern in Fast Craftsmanship:

  • Functions return Result[T, E] types representing success or failure
  • Errors propagate through pipelines of functions
  • Effect functions (@effect.result) for sequential operations
  • Explicit error handling without exceptions

Command Pattern

Commands follow a consistent pattern:

  1. Parse and validate input
  2. Execute the command logic
  3. Return a Result with the output or errors
  4. Format and display the result

Dependency Injection

The architecture uses a form of dependency injection:

  • Functions receive their dependencies as parameters
  • Higher-order functions compose behavior
  • No global state or singletons
  • Easy to test with mocks and stubs

File Organization

The project follows this file organization:

fcship/
├── __init__.py
├── cli.py               # Main CLI entry point
├── commands/            # Command implementations
│   ├── __init__.py      # Command registration
│   ├── github/          # GitHub commands
│   ├── project/         # Project commands
│   └── ...
├── templates/           # Templates for code generation
│   ├── __init__.py
│   └── ...
├── tui/                 # Text UI components
│   ├── __init__.py
│   └── ...
└── utils/               # Utility functions
    ├── __init__.py
    └── ...

Error Handling

Fast Craftsmanship uses a structured approach to error handling:

  1. Functions return Result[T, E] types
  2. Error types are well-defined and descriptive
  3. Errors propagate through function pipelines
  4. TUI layer formats errors for display

Testing Strategy

The testing strategy follows these principles:

  1. Unit Tests: Test individual functions in isolation
  2. Integration Tests: Test command execution end-to-end
  3. Mocks and Stubs: Use mocks for external dependencies
  4. Property Testing: Use property-based testing for invariants
  5. Coverage: Maintain high test coverage

Future Improvements

Areas for future architectural improvements:

  1. Plugin System: Allow for custom commands and extensions
  2. Event System: Implement an event system for loose coupling
  3. Caching: Add caching for expensive operations
  4. Parallelism: Add support for parallel execution of tasks
  5. Config Management: Enhance configuration management