22
33> This file serves as a comprehensive guide for developers working with the StructKit project. It contains project-specific conventions, development workflows, and institutional knowledge.
44
5- ## 📋 Table of Contents
6-
7- - [ Project Overview] ( #project-overview )
8- - [ Development Environment] ( #development-environment )
9- - [ Code Structure] ( #code-structure )
10- - [ Development Workflow] ( #development-workflow )
11- - [ Testing Guidelines] ( #testing-guidelines )
12- - [ Code Style & Standards] ( #code-style--standards )
13- - [ Release Process] ( #release-process )
14- - [ Common Tasks] ( #common-tasks )
15- - [ Troubleshooting] ( #troubleshooting )
16- - [ Architecture Decisions] ( #architecture-decisions )
17- - [ Performance Considerations] ( #performance-considerations )
18- - [ Security Guidelines] ( #security-guidelines )
19- - [ Documentation Standards] ( #documentation-standards )
20- - [ Dependencies & Tools] ( #dependencies--tools )
21- - [ Monitoring & Observability] ( #monitoring--observability )
22- - [ Issue & Work Management] ( #issue--work-management )
23-
245## 🎯 Project Overview
256
267### Mission
8+
279StructKit simplifies project organization by creating consistent file and folder structures tailored to specific needs. It enhances productivity and maintains uniformity across projects through YAML-based configuration files.
2810
2911### Key Features
12+
3013- ** YAML-Based Configuration** : Simple, readable project structure definitions
3114- ** Template Variables** : Dynamic content with Jinja2 templating and interactive prompts
3215- ** Remote Content Fetching** : Support for GitHub, HTTP/HTTPS, S3, and Google Cloud Storage
@@ -35,6 +18,7 @@ StructKit simplifies project organization by creating consistent file and folder
3518- ** MCP Integration** : Model Context Protocol support for AI-assisted workflows
3619
3720### Technology Stack
21+
3822- ** Language** : Python 3.12+
3923- ** CLI Framework** : argparse with custom command pattern
4024- ** Templating** : Jinja2 with custom delimiters
@@ -46,6 +30,7 @@ StructKit simplifies project organization by creating consistent file and folder
4630## 🛠 Development Environment
4731
4832### Prerequisites
33+
4934``` bash
5035# Python 3.12 or higher
5136python --version
@@ -62,6 +47,7 @@ pip install -r requirements.dev.txt
6247```
6348
6449### Environment Variables
50+
6551``` bash
6652# Optional: OpenAI API key for AI features
6753export OPENAI_API_KEY=" your-api-key-here"
@@ -74,14 +60,16 @@ export STRUCTKIT_LOG_LEVEL="DEBUG"
7460```
7561
7662### IDE Configuration
63+
7764- ** VS Code** : Recommended extensions in ` .vscode/extensions.json `
7865- ** PyCharm** : Python interpreter should point to ` .venv/bin/python `
7966- ** Pre-commit hooks** : Run ` pre-commit install ` after setup
8067
8168## 🏗 Code Structure
8269
8370### Directory Layout
84- ```
71+
72+ ``` text
8573structkit/
8674├── commands/ # CLI command implementations
8775│ ├── generate.py # Main generation command
@@ -104,17 +92,20 @@ examples/ # Example configurations
10492### Key Modules
10593
10694#### ` template_renderer.py `
95+
10796- Handles Jinja2 templating with custom delimiters
10897- Interactive variable prompting with descriptions
10998- Type coercion and validation
11099- Icon-based user interface
111100
112101#### ` file_item.py `
102+
113103- Represents files to be created/modified
114104- Handles different content sources (inline, remote, etc.)
115105- Implements file creation strategies (overwrite, skip, backup, etc.)
116106
117107#### ` commands/ `
108+
118109- Each command is a separate class inheriting from ` Command `
119110- Self-contained argument parsing and execution logic
120111- Consistent error handling and logging
@@ -272,17 +263,20 @@ pre-commit run --all-files
272263### Common Issues
273264
274265#### Template Variables Not Resolving
266+
275267- Check custom delimiters: ` {{@ ` ` @}} `
276268- Verify variable names match configuration
277269- Check for typos in YAML structure
278270
279271#### File Creation Failures
272+
280273- Verify file permissions
281274- Check disk space
282275- Validate file paths (no invalid characters)
283276- Review file strategy settings
284277
285278#### Import Errors
279+
286280- Ensure virtual environment is activated
287281- Check Python version compatibility
288282- Verify all dependencies installed: ` pip install -r requirements.txt `
@@ -309,18 +303,21 @@ structkit generate config.yaml --output console
309303## 🏛 Architecture Decisions
310304
311305### Template Engine Choice (Jinja2)
306+
312307- ** Decision** : Use Jinja2 with custom delimiters
313308- ** Rationale** : Mature, well-documented, powerful
314309- ** Trade-offs** : Custom delimiters prevent YAML conflicts
315310- ** Date** : 2024-07-11
316311
317312### Command Pattern Implementation
313+
318314- ** Decision** : Each CLI command is a separate class
319315- ** Rationale** : Modular, testable, extensible
320316- ** Trade-offs** : Slightly more boilerplate
321317- ** Date** : 2024-07-15
322318
323319### File Strategy System
320+
324321- ** Decision** : Pluggable file handling strategies
325322- ** Rationale** : Flexibility for different use cases
326323- ** Trade-offs** : Increased complexity
0 commit comments