Modular Architecture

This document serves as the master index and architectural overview for the modular bearflare.sh codebase.

Module Hierarchy Overview

The bearflare.sh codebase has been modularized into 8 distinct module directories under src/lib/:

Module Directory	Purpose	Category
utils/	Core utilities and timing helpers (foundation layer)	Foundation
logging/	Logging system with rotation and ANSI stripping	Infrastructure
config/	Configuration loading with priority system	Infrastructure
cli/	Command-line argument parsing and validation	Interface
bear/	Bear.app database operations (validation, schema, data)	Domain
cloudflare/d1/	Cloudflare D1 API integration (api, sync)	Domain
data/	Data batching and SQL transformations	Domain
sync/	High-level sync orchestration (schema, data, validation)	Orchestration

Architecture Diagram

graph TD
    subgraph Foundation
        UC[utils/core.sh]
        UT[utils/timing.sh]
    end

    subgraph Infrastructure
        LOG[logging/logger.sh]
        CL[config/loader.sh]
        CV[config/validator.sh]
    end

    subgraph Interface
        CH[cli/help.sh]
        CP[cli/parser.sh]
        CVL[cli/validator.sh]
    end

    subgraph Domain
        BV[bear/validation.sh]
        BS[bear/schema.sh]
        BD[bear/data.sh]
        DA[cloudflare/d1/api.sh]
        DS[cloudflare/d1/sync.sh]
        DB[data/batching.sh]
    end

    subgraph Orchestration
        SS[sync/schema.sh]
        SD[sync/data.sh]
        SV[sync/validation.sh]
    end

    LOG --> UC
    LOG --> UT
    CL --> LOG
    CL --> UT
    CV --> LOG
    CP --> UC
    CP --> LOG
    CP --> CH
    CVL --> UC
    CVL --> LOG
    CVL --> CH
    BV --> LOG
    BV --> UT
    BV --> UC
    BS --> LOG
    BS --> UC
    BD --> LOG
    BD --> UC
    DB --> UC
    DA --> UC
    DS --> DA
    DS --> LOG
    SS --> BS
    SS --> DA
    SS --> UT
    SS --> UC
    SS --> LOG
    SD --> BD
    SD --> DB
    SD --> DS
    SD --> DA
    SD --> UT
    SD --> UC
    SD --> LOG
    SV --> DS
    SV --> DA
    SV --> UT
    SV --> UC
    SV --> LOG

Module Dependency Matrix

Module Name	Direct Dependencies
utils/core.sh	None
utils/timing.sh	utils/core.sh
logging/logger.sh	utils/core.sh, utils/timing.sh
config/loader.sh	logging/logger.sh, utils/timing.sh
config/validator.sh	logging/logger.sh
cli/help.sh	None
cli/parser.sh	utils/core.sh, logging/logger.sh, cli/help.sh
cli/validator.sh	utils/core.sh, logging/logger.sh, cli/help.sh
data/batching.sh	utils/core.sh
cloudflare/d1/api.sh	utils/core.sh
cloudflare/d1/sync.sh	cloudflare/d1/api.sh, logging/logger.sh
bear/validation.sh	logging/logger.sh, utils/timing.sh, utils/core.sh
bear/schema.sh	logging/logger.sh, utils/core.sh
bear/data.sh	logging/logger.sh, utils/core.sh
sync/schema.sh	bear/schema.sh, cloudflare/d1/api.sh, utils/timing.sh, utils/core.sh, logging/logger.sh
sync/data.sh	bear/data.sh, data/batching.sh, cloudflare/d1/sync.sh, cloudflare/d1/api.sh, utils/timing.sh, utils/core.sh, logging/logger.sh
sync/validation.sh	cloudflare/d1/sync.sh, cloudflare/d1/api.sh, utils/timing.sh, utils/core.sh, logging/logger.sh

Sourcing Order

Modules must be sourced in dependency order:

1. Foundation Layer: utils/core.sh, utils/timing.sh
2. Infrastructure Layer: logging/logger.sh, config/loader.sh, config/validator.sh
3. Interface Layer: cli/help.sh, cli/parser.sh, cli/validator.sh
4. Domain Layer: data/batching.sh, cloudflare/d1/api.sh, cloudflare/d1/sync.sh, bear/validation.sh, bear/schema.sh, bear/data.sh
5. Orchestration Layer: sync/schema.sh, sync/data.sh, sync/validation.sh

Module Navigation Links

• Utils Module - Core utilities and timing helpers
• Logging Module - Logging system
• Config Module - Configuration loading and validation
• CLI Module - CLI argument parsing and validation
• Bear Module - Bear database operations
• Cloudflare D1 Module - Cloudflare D1 API integration
• Data Module - Data batching and transformations
• Sync Module - Sync orchestration workflows

Navigation

• Architecture Overview - High-level architecture and design patterns
• CLI Module - Command-line interface
• Config Module - Configuration management
• Logging Module - Logging system
• Bear Module - Bear database operations
• Cloudflare D1 Module - D1 API integration
• Data Module - Data batching and transformations
• Sync Module - Sync orchestration
• Utils Module - Core utilities