Skip to content

Commit 50e5c58

Browse files
emcdclaude
emcd
and
claude
committed
Architecture Documentation: Add comprehensive system architecture foundation.
- Add cs-architect slash command for specialized architectural analysis - Create comprehensive system overview with three-tier architecture documentation - Document major components, data flows, and deployment architecture - Add ADR-001: Three-tier architecture decision with alternatives analysis - Add ADR-002: Centralized import pattern decision with rationale - Create project-specific filesystem organization documentation - Establish architectural decision record foundation for future decisions 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 82142b8 commit 50e5c58

6 files changed

Lines changed: 717 additions & 2 deletions

File tree

‎.auxiliary/configuration/claude/commands/cs-architect.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
allowed-tools: [Read, Write, Edit, MultiEdit, LS, Glob, Grep]
3+
description: Architectural analysis, system design decisions, and ADR creation
4+
---
5+
6+
# System Architecture Analysis
7+
8+
Analyze architectural decisions, system design patterns, component
9+
relationships, and technical trade-offs to provide guidance on high-level
10+
system structure.
11+
12+
Request from user: $ARGUMENTS
13+
14+
Stop and consult if:
15+
- Implementation details are requested instead of architectural guidance
16+
- Specific code changes are needed
17+
- Requirements analysis is needed
18+
19+
## Context
20+
21+
- Product requirements: @documentation/prd.rst
22+
- Architecture overview: @documentation/architecture/summary.rst
23+
- Filesystem patterns: @documentation/architecture/filesystem.rst
24+
- Architecture guidelines: @.auxiliary/instructions/architecture.rst
25+
- Current project state: !`find documentation/architecture -name "*.rst" | head -10`
26+
27+
## Prerequisites
28+
29+
Before providing architectural analysis, ensure:
30+
- Understanding of current system architecture and constraints
31+
- Familiarity with architectural decision record (ADR) format
32+
- Knowledge of standard filesystem organization patterns
33+
- @.auxiliary/instructions/architecture.rst guidelines are followed
34+
35+
## Process Summary
36+
37+
Key functional areas:
38+
1. **Analysis**: Examine architectural context and design forces
39+
2. **Decision Framework**: Apply architectural principles and trade-off analysis
40+
3. **Documentation**: Create ADRs or update architectural documentation
41+
4. **Validation**: Ensure decisions align with project constraints and goals
42+
43+
## Safety Requirements
44+
45+
Stop and consult the user if:
46+
- Architectural decisions have significant impact on existing system components
47+
- Decision conflicts with existing architectural patterns or constraints
48+
- Decision requires changes to fundamental system assumptions
49+
50+
## Execution
51+
52+
Execute the following steps:
53+
54+
### 1. Architectural Context Analysis
55+
Review current architecture and identify relevant patterns:
56+
- Examine existing architectural documentation
57+
- Understand system boundaries and component relationships
58+
- Identify architectural forces and constraints
59+
- Assess alignment with project goals and requirements
60+
61+
### 2. Design Forces Assessment
62+
Analyze the forces driving the architectural decision:
63+
- Technical constraints (performance, scalability, compatibility)
64+
- Quality attributes (maintainability, testability, security)
65+
- Integration requirements with existing components
66+
- Future flexibility and evolution needs
67+
68+
### 3. Alternative Evaluation
69+
Consider multiple architectural approaches:
70+
- Document all seriously considered alternatives
71+
- Analyze trade-offs for each option (benefits, costs, risks)
72+
- Consider "do nothing" as a baseline alternative
73+
- Evaluate alignment with established architectural patterns
74+
- Assess implementation complexity and maintenance burden
75+
76+
### 4. Decision Recommendation
77+
Provide clear architectural guidance:
78+
- State recommended approach with clear rationale
79+
- Explain how decision addresses the identified forces
80+
- Document expected positive and negative consequences
81+
- Include specific architectural patterns or principles applied
82+
- Provide text-based diagrams or examples when helpful
83+
84+
### 5. Documentation Creation
85+
When appropriate, create or update architectural documentation:
86+
- Generate ADRs following the standard format
87+
- Update architecture summary for significant system changes
88+
- Ensure consistency with filesystem organization patterns
89+
- Reference related architectural decisions and dependencies
90+
91+
### 6. Implementation Guidance
92+
Provide high-level implementation direction without specific code:
93+
- Suggest component organization and interfaces
94+
- Recommend integration patterns with existing system
95+
- Identify key architectural boundaries and abstractions
96+
- Highlight critical implementation considerations
97+
98+
### 7. Summarize Updates
99+
Provide concise summary of updates to the user.

‎documentation/architecture/decisions/001-three-tier-architecture.rst‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
.. vim: set fileencoding=utf-8:
2+
.. -*- coding: utf-8 -*-
3+
.. +--------------------------------------------------------------------------+
4+
| |
5+
| Licensed under the Apache License, Version 2.0 (the "License"); |
6+
| you may not use this file except in compliance with the License. |
7+
| You may obtain a copy of the License at |
8+
| |
9+
| http://www.apache.org/licenses/LICENSE-2.0 |
10+
| |
11+
| Unless required by applicable law or agreed to in writing, software |
12+
| distributed under the License is distributed on an "AS IS" BASIS, |
13+
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
14+
| See the License for the specific language governing permissions and |
15+
| limitations under the License. |
16+
| |
17+
+--------------------------------------------------------------------------+
18+
19+
20+
*******************************************************************************
21+
001. Three-Tier Architecture for Project Lifecycle Management
22+
*******************************************************************************
23+
24+
Status
25+
===============================================================================
26+
27+
Accepted
28+
29+
Context
30+
===============================================================================
31+
32+
The Python Project Common system needs to address the complete project lifecycle from initial creation through ongoing maintenance. The system must support:
33+
34+
- **Project Creation**: Rapid scaffolding of new Python projects with consistent structure
35+
- **Development Workflow**: Automated CI/CD pipelines with quality gates and cross-platform testing
36+
- **Maintenance Operations**: Ongoing documentation updates, coverage reporting, and template synchronization
37+
38+
Key forces driving the architectural decision:
39+
40+
**Separation of Concerns**: Different lifecycle phases have distinct requirements, tools, and update frequencies. Template generation happens once per project, CI/CD runs on every commit, and maintenance operations occur periodically.
41+
42+
**Tool Integration**: Each phase integrates with different toolsets - Copier for templating, GitHub Actions for automation, Python packaging for maintenance tools.
43+
44+
**Deployment Flexibility**: Components should deploy independently and scale based on usage patterns.
45+
46+
**Maintenance Overhead**: Architecture must accommodate single-maintainer model with community contributions.
47+
48+
Decision
49+
===============================================================================
50+
51+
Implement a three-tier architecture separating template generation, workflow automation, and maintenance tooling into distinct layers:
52+
53+
**Tier 1: Template Generation Layer**
54+
- Copier-based project scaffolding system
55+
- Jinja2 templating with conditional feature support
56+
- Configuration management via copier.yaml
57+
58+
**Tier 2: CI/CD Automation Layer**
59+
- Reusable GitHub Actions workflow components
60+
- Cross-platform testing matrix execution
61+
- Quality gates and release automation
62+
63+
**Tier 3: Project Maintenance Layer**
64+
- Python package (emcd-projects) for runtime maintenance
65+
- Static site generation and badge management
66+
- Template synchronization and update tooling
67+
68+
Each tier operates independently with well-defined interfaces and can evolve at different rates based on requirements.
69+
70+
Alternatives
71+
===============================================================================
72+
73+
**Monolithic Architecture**
74+
- Single integrated tool handling all lifecycle phases
75+
- Rejected due to complexity of integrating disparate toolsets (Copier, GitHub Actions, Python packaging)
76+
- Would create tight coupling between template changes and maintenance operations
77+
- Difficult to scale individual components based on usage patterns
78+
79+
**Microservices Architecture**
80+
- Fine-grained services for each operation (templating, testing, documentation, etc.)
81+
- Rejected due to operational complexity for single-maintainer model
82+
- Network dependencies would reduce reliability for template generation
83+
- Overhead of service orchestration outweighs benefits for this use case
84+
85+
**Two-Tier Architecture (Template + Runtime)**
86+
- Combine CI/CD automation with maintenance tooling
87+
- Rejected because CI/CD and maintenance have fundamentally different execution contexts
88+
- GitHub Actions workflows require different deployment and versioning patterns than Python packages
89+
- Would blur boundaries between build-time and runtime operations
90+
91+
Consequences
92+
===============================================================================
93+
94+
**Positive Consequences**
95+
96+
**Clear Separation of Concerns**: Each tier has well-defined responsibilities and can evolve independently. Template changes don't require maintenance tool updates and vice versa.
97+
98+
**Tool Integration Flexibility**: Each tier can leverage best-of-breed tools for its specific domain without compromising other layers.
99+
100+
**Independent Scaling**: Template generation scales with new project creation, CI/CD scales with commit frequency, maintenance scales with project count.
101+
102+
**Maintainability**: Clear architectural boundaries make the system easier to understand, debug, and extend.
103+
104+
**Community Contribution**: Contributors can work on specific tiers without understanding the entire system.
105+
106+
**Negative Consequences**
107+
108+
**Integration Complexity**: Three separate systems require coordination for end-to-end workflows.
109+
110+
**Version Synchronization**: Changes affecting multiple tiers require careful coordination to maintain compatibility.
111+
112+
**Testing Overhead**: Integration testing must verify correct operation across all three tiers.
113+
114+
**Documentation Burden**: Each tier requires separate documentation and architectural decision tracking.
115+
116+
**Neutral Consequences**
117+
118+
**Deployment Diversity**: Each tier uses different deployment mechanisms (Git repository, GitHub Actions marketplace, PyPI), which matches their different execution contexts but requires diverse operational knowledge.
119+
120+
**Technology Stack Diversity**: Each tier uses appropriate technologies (Jinja2, GitHub Actions YAML, Python) rather than forcing a single technology across all tiers.

‎documentation/architecture/decisions/002-centralized-import-pattern.rst‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
.. vim: set fileencoding=utf-8:
2+
.. -*- coding: utf-8 -*-
3+
.. +--------------------------------------------------------------------------+
4+
| |
5+
| Licensed under the Apache License, Version 2.0 (the "License"); |
6+
| you may not use this file except in compliance with the License. |
7+
| You may obtain a copy of the License at |
8+
| |
9+
| http://www.apache.org/licenses/LICENSE-2.0 |
10+
| |
11+
| Unless required by applicable law or agreed to in writing, software |
12+
| distributed under the License is distributed on an "AS IS" BASIS, |
13+
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
14+
| See the License for the specific language governing permissions and |
15+
| limitations under the License. |
16+
| |
17+
+--------------------------------------------------------------------------+
18+
19+
20+
*******************************************************************************
21+
002. Centralized Import Management via __ Subpackage Pattern
22+
*******************************************************************************
23+
24+
Status
25+
===============================================================================
26+
27+
Accepted
28+
29+
Context
30+
===============================================================================
31+
32+
Python projects generated from this template need consistent import management across modules to address several challenges:
33+
34+
**Namespace Pollution**: Individual modules importing common dependencies directly leads to namespace pollution and makes module interfaces unclear.
35+
36+
**Import Duplication**: Common imports (collections.abc, immutable containers, type hints) are repeated across many modules, creating maintenance overhead.
37+
38+
**Performance Considerations**: Repeated import costs across modules can impact package initialization time.
39+
40+
**Maintenance Overhead**: Changes to common dependencies require updates across multiple modules.
41+
42+
**Code Readability**: Module code becomes cluttered with import statements rather than focusing on core functionality.
43+
44+
The template system must provide a scalable solution that works consistently across:
45+
- Single-package projects
46+
- Multi-package projects with subpackages
47+
- Projects with varying complexity levels
48+
- Projects using different optional features (CLI, Rust extensions, etc.)
49+
50+
Decision
51+
===============================================================================
52+
53+
Implement centralized import management using the double underscore (``__``) subpackage pattern:
54+
55+
**Core Implementation**:
56+
- Every Python package includes a ``__`` subdirectory
57+
- Contains ``__init__.py`` (re-exports), ``imports.py`` (raw imports), ``nomina.py`` (naming constants)
58+
- All modules use identical ``from . import __`` import pattern
59+
60+
**Hierarchical Extension**:
61+
- Subpackages implement cascading imports with ``from ..__ import *``
62+
- Each level can add specialized imports without duplicating parent imports
63+
- Maintains consistent interface regardless of package depth
64+
65+
**Template Integration**:
66+
- Template system generates appropriate ``__`` structure based on project features
67+
- Optional components (CLI, Rust, etc.) extend the import hierarchy as needed
68+
- Standard imports are pre-configured for immediate development productivity
69+
70+
Alternatives
71+
===============================================================================
72+
73+
**Direct Module Imports**
74+
- Each module imports dependencies directly
75+
- Rejected due to namespace pollution and maintenance overhead
76+
- Would require updating every module when common dependencies change
77+
- Creates inconsistent import patterns across project modules
78+
79+
**Package-Level __init__.py Imports**
80+
- Central imports at package ``__init__.py`` level
81+
- Rejected because it pollutes the main package namespace
82+
- Makes it unclear which imports are part of the public API vs internal dependencies
83+
- Doesn't scale well to multi-package projects
84+
85+
**Import Utility Module**
86+
- Single ``imports.py`` or ``utils.py`` module with all dependencies
87+
- Rejected because it creates a monolithic import module that becomes unwieldy
88+
- Doesn't provide clear organization for different types of imports
89+
- No natural extension pattern for subpackages
90+
91+
**Per-Module Import Files**
92+
- Each module has an associated ``_imports.py`` file
93+
- Rejected due to file proliferation and maintenance complexity
94+
- Creates 2x file count for every functional module
95+
- No clear inheritance pattern for shared imports
96+
97+
Consequences
98+
===============================================================================
99+
100+
**Positive Consequences**
101+
102+
**Consistent Interface**: All modules use identical ``from . import __`` regardless of package depth or complexity, reducing cognitive load.
103+
104+
**Namespace Clarity**: Module namespaces contain only module-specific functionality, making interfaces clearer and more maintainable.
105+
106+
**Maintenance Efficiency**: Common import changes propagate automatically to all modules without requiring individual module updates.
107+
108+
**Performance Optimization**: Import costs are centralized to package initialization, enabling strategic optimization for performance-critical paths.
109+
110+
**Scalability**: Pattern extends naturally from simple single-package projects to complex multi-package hierarchies without changing the interface.
111+
112+
**Template Flexibility**: Template system can generate appropriate import structures based on selected features without affecting module code patterns.
113+
114+
**Negative Consequences**
115+
116+
**Learning Curve**: Developers unfamiliar with the pattern require education about the import hierarchy and naming conventions.
117+
118+
**Initial Setup Complexity**: Each package requires proper ``__`` subpackage setup, though this is handled by the template system.
119+
120+
**Import Resolution Indirection**: Imports go through an additional layer of indirection, though this is minimal performance impact.
121+
122+
**Debugging Complexity**: Import-related debugging requires understanding the cascading import hierarchy.
123+
124+
**Neutral Consequences**
125+
126+
**File Structure Overhead**: Each package contains additional ``__`` subdirectory structure, but this is consistent and predictable.
127+
128+
**IDE Integration**: Modern IDEs handle the import pattern well, providing proper autocompletion and navigation through the import hierarchy.
129+
130+
**Convention Enforcement**: Pattern requires discipline to maintain, but template system and documentation provide clear guidance.

‎documentation/architecture/decisions/index.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,9 @@ Architectural Decision Records
2424
.. toctree::
2525
:maxdepth: 2
2626

27+
001-three-tier-architecture
28+
002-centralized-import-pattern
2729

28-
.. todo:: Add architectural decision records to toctree.
30+
Additional ADRs will be created as the system evolves and new architectural decisions are required.
2931

3032
For ADR format and guidance, see :doc:`../../common/architecture`.

0 commit comments

Comments
 (0)