# Project Structure This document explains the organization of the Tasmota Berry Animation Framework project. ## Root Directory ``` ├── README.md # Main project overview and quick start ├── docs/ # User documentation ├── lib/libesp32/berry_animation/ # Framework source code ├── anim_examples/ # DSL animation examples (.anim files) ├── anim_examples/compiled/ # Compiled Berry code from DSL examples ├── .kiro/ # Project specifications and design docs └── .docs_archive/ # Archived technical implementation docs ``` ## Documentation (`docs/`) User-focused documentation for learning and using the framework: ``` docs/ ├── QUICK_START.md # 5-minute getting started guide ├── API_REFERENCE.md # Complete Berry API documentation ├── EXAMPLES.md # Curated examples with explanations ├── TROUBLESHOOTING.md # Common issues and solutions └── PROJECT_STRUCTURE.md # This file ``` ## Framework Source Code (`lib/libesp32/berry_animation/`) The complete framework implementation: ``` lib/libesp32/berry_animation/ ├── animation.be # Main module entry point ├── README.md # Framework-specific readme ├── user_functions.be # Example user-defined functions │ ├── core/ # Core framework classes │ ├── animation_base.be # Animation base class │ ├── animation_engine.be # Unified animation engine │ ├── event_handler.be # Event system │ ├── frame_buffer.be # Frame buffer management │ ├── pattern_base.be # Pattern base class │ ├── sequence_manager.be # Sequence orchestration │ └── user_functions.be # User function registry │ ├── effects/ # Animation implementations │ ├── breathe.be # Breathing animation │ ├── comet.be # Comet effect │ ├── crenel_position.be # Rectangular pulse patterns │ ├── filled.be # Filled animations │ ├── fire.be # Fire simulation │ ├── palette_pattern.be # Palette-based patterns │ ├── palettes.be # Predefined palettes │ ├── pattern_animation.be # Pattern wrapper animation │ ├── pulse.be # Pulse animation │ ├── pulse_position.be # Position-based pulse │ └── twinkle.be # Twinkling stars │ ├── patterns/ # Pattern implementations │ └── solid_pattern.be # Solid color pattern │ ├── providers/ # Value and color providers │ ├── color_cycle_color_provider.be # Color cycling │ ├── color_provider.be # Base color provider │ ├── composite_color_provider.be # Blended colors │ ├── oscillator_value_provider.be # Waveform generators │ ├── rich_palette_color_provider.be # Palette-based colors │ ├── solid_color_provider.be # Static colors │ ├── static_value_provider.be # Static value wrapper │ └── value_provider.be # Base value provider │ ├── dsl/ # Domain-Specific Language │ ├── lexer.be # DSL tokenizer │ ├── runtime.be # DSL execution runtime │ ├── token.be # Token definitions │ └── transpiler.be # DSL to Berry transpiler │ ├── tests/ # Comprehensive test suite │ ├── test_all.be # Run all tests │ ├── animation_engine_test.be │ ├── dsl_transpiler_test.be │ ├── event_system_test.be │ └── ... (50+ test files) │ ├── examples/ # Berry code examples │ ├── run_all_demos.be # Run all examples │ ├── simple_engine_test.be # Basic usage │ ├── color_provider_demo.be # Color system demo │ ├── event_system_demo.be # Interactive animations │ └── ... (60+ example files) │ └── docs/ # Framework-specific documentation ├── architecture_simplification.md ├── class_hierarchy_reference.md ├── migration_guide.md └── ... (technical documentation) ``` ## DSL Examples (`anim_examples/`) Ready-to-use animation files in DSL format: ``` anim_examples/ ├── aurora_borealis.anim # Northern lights effect ├── breathing_colors.anim # Smooth color breathing ├── fire_demo.anim # Realistic fire simulation ├── palette_demo.anim # Palette showcase ├── rainbow_cycle.anim # Rainbow color cycling └── simple_pulse.anim # Basic pulsing effect ``` ## Compiled Examples (`anim_examples/compiled/`) Berry code generated from DSL examples (for reference): ``` anim_examples/compiled/ ├── aurora_borealis.be # Compiled from aurora_borealis.anim ├── breathing_colors.be # Compiled from breathing_colors.anim └── ... (compiled versions of .anim files) ``` ## Project Specifications (`.kiro/specs/berry-animation-framework/`) Design documents and specifications: ``` .kiro/specs/berry-animation-framework/ ├── design.md # Architecture overview ├── requirements.md # Project requirements (✅ complete) ├── dsl-specification.md # DSL syntax reference ├── dsl-grammar.md # DSL grammar specification ├── EVENT_SYSTEM.md # Event system documentation ├── USER_FUNCTIONS.md # User-defined functions guide ├── palette-quick-reference.md # Palette usage guide └── future_features.md # Planned enhancements ``` ## Archived Documentation (`.docs_archive/`) Technical implementation documents moved from active documentation: ``` .docs_archive/ ├── dsl-transpiler-architecture.md # Detailed transpiler design ├── dsl-implementation.md # Implementation details ├── color_provider_system.md # Color system internals ├── unified-architecture-summary.md # Architecture migration notes └── ... (50+ archived technical docs) ``` ## Key Files for Different Use Cases ### Getting Started 1. **`README.md`** - Project overview and quick examples 2. **`docs/QUICK_START.md`** - 5-minute tutorial 3. **`anim_examples/simple_pulse.anim`** - Basic DSL example ### Learning the API 1. **`docs/API_REFERENCE.md`** - Complete API documentation 2. **`docs/EXAMPLES.md`** - Curated examples with explanations 3. **`lib/libesp32/berry_animation/examples/simple_engine_test.be`** - Basic Berry usage ### Using the DSL 1. **`.kiro/specs/berry-animation-framework/dsl-specification.md`** - Complete DSL syntax 2. **`.kiro/specs/berry-animation-framework/palette-quick-reference.md`** - Palette guide 3. **`anim_examples/`** - Working DSL examples ### Advanced Features 1. **`.kiro/specs/berry-animation-framework/USER_FUNCTIONS.md`** - Custom functions 2. **`.kiro/specs/berry-animation-framework/EVENT_SYSTEM.md`** - Interactive animations 3. **`lib/libesp32/berry_animation/user_functions.be`** - Example custom functions ### Troubleshooting 1. **`docs/TROUBLESHOOTING.md`** - Common issues and solutions 2. **`lib/libesp32/berry_animation/tests/test_all.be`** - Run all tests 3. **`lib/libesp32/berry_animation/examples/run_all_demos.be`** - Test examples ### Framework Development 1. **`.kiro/specs/berry-animation-framework/design.md`** - Architecture overview 2. **`.kiro/specs/berry-animation-framework/requirements.md`** - Project requirements 3. **`lib/libesp32/berry_animation/tests/`** - Test suite for development ## File Naming Conventions ### Source Code - **`*.be`** - Berry source files - **`*_test.be`** - Test files - **`*_demo.be`** - Example/demonstration files ### Documentation - **`*.md`** - Markdown documentation - **`README.md`** - Overview documents - **`QUICK_START.md`** - Getting started guides - **`API_REFERENCE.md`** - API documentation ### DSL Files - **`*.anim`** - DSL animation files - **`*.be`** (in anim_examples/compiled/) - Compiled Berry code from DSL ## Navigation Tips ### For New Users 1. Start with `README.md` for project overview 2. Follow `docs/QUICK_START.md` for hands-on tutorial 3. Browse `anim_examples/` for inspiration 4. Reference `docs/API_REFERENCE.md` when needed ### For DSL Users 1. Learn syntax from `.kiro/specs/berry-animation-framework/dsl-specification.md` 2. Study examples in `anim_examples/` 3. Use palette guide: `.kiro/specs/berry-animation-framework/palette-quick-reference.md` 4. Create custom functions: `.kiro/specs/berry-animation-framework/USER_FUNCTIONS.md` ### For Berry Developers 1. Study `lib/libesp32/berry_animation/examples/simple_engine_test.be` 2. Reference `docs/API_REFERENCE.md` for complete API 3. Run tests: `lib/libesp32/berry_animation/tests/test_all.be` 4. Explore advanced examples in `lib/libesp32/berry_animation/examples/` ### For Framework Contributors 1. Understand architecture: `.kiro/specs/berry-animation-framework/design.md` 2. Review requirements: `.kiro/specs/berry-animation-framework/requirements.md` 3. Study source code in `lib/libesp32/berry_animation/core/` 4. Run comprehensive tests: `lib/libesp32/berry_animation/tests/test_all.be` This structure provides clear separation between user documentation, source code, examples, and technical specifications, making it easy to find relevant information for any use case.