Skip to content

ARCHITECTURE_DECISION.md

Latest commit

 

History

History
143 lines (110 loc) · 4.95 KB

ARCHITECTURE_DECISION.md

File metadata and controls

143 lines (110 loc) · 4.95 KB

Architecture Decision: Not Aligning with Electron-React-Boilerplate

Date: 2025-11-14
Status: Decided
Decision Maker: Development Team

Context

The question was raised whether Lumberjack should be restructured to align with the electron-react-boilerplate project structure, using up-to-date dependencies.

Analysis

Current Lumberjack Architecture

Strengths:

  • Build System: Vite + esbuild - fast, simple, modern
  • UI Framework: Preact (3KB) - lightweight and performant
  • Bundle Size: 38KB main bundle (12KB gzipped)
  • Structure: Clean, flat organization with logical separation (main/, renderer/, services/, utils/)
  • Performance: Highly optimized with:
    • Web workers for background processing
    • Service workers for caching
    • Virtual scrolling for large datasets
    • Adaptive batch processing
    • Circuit breaker pattern
    • Token bucket rate limiting
    • Health monitoring
    • Non-blocking async file I/O

Build Times:

  • Main build: ~18ms
  • Preload build: ~2ms
  • Renderer build: ~1.17s
  • Total: ~1.2s

Electron-React-Boilerplate Architecture

Characteristics:

  • Build System: Webpack with extensive configuration in .erb/ folder
  • UI Framework: React (40KB+) - full version with more features
  • Focus: General-purpose boilerplate template for new projects
  • Features: Hot reload, DLL bundling, comprehensive testing setup
  • Complexity: Multiple webpack configs, scripts, and build steps

Decision

We will NOT align Lumberjack with electron-react-boilerplate.

Reasons

  1. Performance Optimizations Would Be Lost

    • Lumberjack's 38KB bundle vs typical React apps 200KB+
    • Advanced production-ready features (adaptive batching, circuit breakers, health monitoring) would need to be re-implemented
    • Sub-second build times would increase significantly

  2. Build System Superiority

    • Vite is faster and simpler than Webpack
    • esbuild provides near-instant compilation
    • No need for complex configuration
    • Better developer experience

  3. UI Library Fit

    • Preact (3KB) is ideal for a performance-focused log viewer
    • React (40KB+) would increase bundle size by 10x+ without providing needed features
    • Preact compatibility with React ecosystem provides access to libraries when needed

  4. Structural Clarity

    • Current flat structure is more maintainable
    • Clear separation of concerns without over-engineering
    • .erb/ folder pattern adds complexity without benefits for this project

  5. Scope of Change

    • Alignment would require a complete rewrite
    • All existing features would need to be re-implemented
    • High risk of breaking existing functionality
    • No clear benefits to justify the cost

  6. Project Maturity

    • Lumberjack is a production application, not a boilerplate
    • Specific optimizations tailored to log viewing use case
    • Migration would discard significant engineering investment

Alternative Action Taken

Instead of restructuring, we:

  1. ✅ Updated all dependencies to their latest versions
  2. ✅ Verified builds and functionality work correctly
  3. ✅ Maintained existing performance optimizations
  4. ✅ Preserved clean architecture

Updated Dependencies

The following dependencies were updated to their latest versions:

DevDependencies:

  • @eslint/js: 9.39.0 → 9.39.1
  • @types/node: 24.9.2 → 24.10.1
  • @typescript-eslint/eslint-plugin: 8.46.2 → 8.46.4
  • @typescript-eslint/parser: 8.46.2 → 8.46.4
  • electron: 39.0.0 → 39.2.0
  • esbuild: 0.25.11 → 0.27.0
  • eslint: 9.39.0 → 9.39.1
  • globals: 16.4.0 → 16.5.0
  • sharp: 0.34.4 → 0.34.5
  • vite: 7.1.12 → 7.2.2
  • wait-on: 9.0.1 → 9.0.3

All dependencies are now on their latest stable versions.

Consequences

Positive:

  • ✅ Dependencies are up-to-date
  • ✅ Performance optimizations preserved
  • ✅ Build system remains fast and simple
  • ✅ No breaking changes to existing codebase
  • ✅ Minimal risk and effort

Neutral:

  • Architecture remains different from electron-react-boilerplate
  • Future developers familiar only with ERB may need to learn Vite/Preact

Negative:

  • None identified

Future Considerations

If there are specific features from electron-react-boilerplate that would benefit Lumberjack, they should be evaluated individually and adopted selectively rather than wholesale restructuring. Examples might include:

  • Testing infrastructure (if not already present)
  • Specific build optimizations
  • Development tooling improvements

Any such adoptions should be evaluated based on:

  1. Clear benefit to the project
  2. Compatibility with existing architecture
  3. Impact on bundle size and performance
  4. Implementation effort vs. value

References