Decision (+6)

Decision

Implement a modular architecture with three independent modules (Invoice Automation, Tax Preparation, Tax Filing) rather than a monolithic business automation system, enabling gradual feature adoption aligned with user needs.

Context

Small engineering firms need flexibility to adopt automation features incrementally:

• Not all firms need all features simultaneously
• Budget constraints limit initial investment
• Different features have different priorities (invoice automation urgent, tax filing seasonal)
• Need to prove value before full system adoption

Modular Approach

Module Structure:

1. Invoice Automation: invoice-gen - Immediate 80% time savings, highest ROI
2. Tax Preparation: tax-prep - Eliminate manual categorization, quarterly benefit
3. Tax Filing: tax-file - Annual compliance automation, seasonal use

Shared Components:

• Configuration management (YAML)
• PDF utilities (pypdf)
• Logging framework (loguru)
• Testing infrastructure (pytest)

See sub-skills for full details.

Alternatives Considered

1. Monolithic All-in-One System

• Pros: Single unified interface, simpler initial architecture
• Cons: All-or-nothing adoption, $25K+ perceived investment, harder to justify ROI
• Why Rejected: Firms want proof-of-value before full investment

2. Microservices

• Pros: Maximum independence, cloud deployment ready
• Cons: Over-engineering for local Python scripts, network complexity
• Why Rejected: Unnecessary complexity for desktop automation

See sub-skills for full details.

Consequences

Positive:

• Gradual Adoption: Firms adopt invoice automation first ($1,950/year value), then expand
• Risk Mitigation: Prove value module-by-module before full investment
• Independent Development: Each module can evolve independently
• Clear Testing: 80% coverage per module, 95% for critical invoice generation
• Flexible Pricing: Could charge per module if productized

Negative:

• More Setup: Three module directories vs. one
• Shared Component Discipline: Must minimize shared code to avoid coupling

See sub-skills for full details.

Implementation

pyproject.toml:

[project.scripts]
invoice-gen = "aceengineer_admin.invoice:main"
tax-prep = "aceengineer_admin.tax_prep:main"
tax-file = "aceengineer_admin.tax_file:main"

Directory Structure:

*See sub-skills for full details.*

## References


- tech-stack.md: Modular Architecture section
- roadmap.md: Phase 1 (Invoice), Phase 2 (Tax Prep), Phase 3 (Filing)
- mission.md: Implementation Approach with phased rollout