chore: added detailed architecture and AI context docs

.github/config/spellcheck-wordlist.txt

@@ -1,24 +1,52 @@
+ActorVariable
+APIs
+AssociatedVariable
+AttributeExpander
+Benchmarking
 Bool
-CocoaPods
+ClassVariable
+Codable
 CodedIn
 CodingKey
+CodingKeys
+CodingKeysMap
+CocoaPods
+ConstraintGenerator
 DateCoder
+Decodable
+DocumentationExtension
+Encodable
+EnumCaseVariable
+EnumSwitcherVariable
+EnumVariable
+ExprRegistration
 Github
 HelperCoder
 HelperCoders
+IgnoreEncoding
 JSON
 LossySequenceCoder
-Codable
-Encodable
-Decodable
 MetaCodable
+MetaCodable's
 MetaProtocolCodable
 Midbin
+PathRegistration
+PluginCore
+Podfile
+Pre
+PropertyVariableTreeNode
 README
 Refactorings
+Runtime
 SPM
+SequenceCoder
+SwiftData
+SwiftFormat
+SwiftUI
 SwiftyLab
 TabNavigator
+Trie
+VSCode
 ValueCoder
 Xcode
 ae
@@ -27,8 +55,15 @@ bc
 boolean
 cb
 cd
+cocoapods
+conformances
+customizable
 da
+datasets
 eb
+enum
+enums
+expander
 faq
 formatters
 getter
@@ -39,30 +74,20 @@ https
 initializer
 initializers
 json
+lowercasing
 macOS
 mahunt
 memberwise
+mergeBehavior
+preprocessing
 sexualized
 socio
 soumya
 structs
 swiftpackageindex
 tvOS
+typealias
 variadic
 vscode
 watchOS
 www
-typealias
-customizable
-enum
-enums
-conformances
-Podfile
-cocoapods
-DocumentationExtension
-mergeBehavior
-lowercasing
-SwiftData
-SwiftUI
-IgnoreEncoding
-VSCode

.github/copilot-instructions.md

@@ -0,0 +1,4 @@
+We follow swift camel case for naming folders and files.
+We use swift-format to for formatting and linting. Custom formatting rules are defined in .swift-format file.
+We use swift testing to write tests.
+Always remove empty spaces in generated code.

CONTRIBUTING.md

@@ -5,9 +5,24 @@ Please read it before you start participating.
 
 _See also: [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md)_
 
+## Developer Documentation
+
+Detailed documentation for contributors is available in the [Contributing](Contributing/README.md) folder:
+
+- [Architecture Overview](Contributing/ARCHITECTURE.md) - Core components and system design
+- [Macro Processing Pipeline](Contributing/MACRO_PROCESSING.md) - Class hierarchy and code generation
+- [Coding Strategies](Contributing/CODING_STRATEGIES.md) - Implementation patterns and helper systems
+- [Build Plugin System](Contributing/BUILD_PLUGIN.md) - Plugin architecture and integration
+- [Testing and Development](Contributing/TESTING.md) - Testing methodology and best practices
+- [Troubleshooting](Contributing/TROUBLESHOOTING.md) - Common issues and solutions
+
 ## Submitting Pull Requests
 
-You can contribute by fixing bugs or adding new features. For larger code changes, we first recommend discussing them in our [Github issues](https://github.com/SwiftyLab/MetaCodable/issues). When submitting a pull request, please add relevant tests and ensure your changes don't break any existing tests (see [Automated Tests](#automated-tests) below).
+You can contribute by fixing bugs or adding new features. For larger code changes, we first recommend:
+1. Review the [Architecture Overview](Contributing/ARCHITECTURE.md) to understand the system
+2. Discuss your proposed changes in our [Github issues](https://github.com/SwiftyLab/MetaCodable/issues)
+3. Read the relevant documentation in the [Contributing](Contributing/README.md) folder
+4. Submit your pull request with appropriate tests (see [Testing](Contributing/TESTING.md))
 
 ### Things you will need
 
@@ -39,7 +54,9 @@ open $PATH_TO_XCODE_INSTALLATION --env METACODABLE_CI=1
 
 ### Automated Tests
 
-GitHub action is already setup to run tests on pull requests targeting `main` branch. However, to reduce heavy usage of GitHub runners, run the following commands in your terminal to test:
+GitHub action is already setup to run tests on pull requests targeting `main` branch. For detailed testing instructions and methodology, see our [Testing Guide](Contributing/TESTING.md).
+
+To run tests locally and reduce usage of GitHub runners:
 
 | Test category | With [Node] | Manually |
 | --- | --- | --- |

Contributing/ARCHITECTURE.md

@@ -0,0 +1,89 @@
+# MetaCodable Architecture
+
+This document provides a high-level overview of MetaCodable's architecture and implementation details.
+
+## Overview
+
+MetaCodable is a Swift macro-based framework that supercharges Swift's `Codable` implementations. It uses the power of Swift macros to generate sophisticated coding logic while keeping the API simple and declarative.
+
+## Core Components
+
+```mermaid
+graph TD
+    A[MetaCodable Core] --> B[Macro System]
+    A --> C[Helper Coders]
+    A --> D[Protocol Generation]
+    B --> E[Attribute Processing]
+    B --> F[Code Generation]
+    C --> G[Built-in Coders]
+    C --> H[Custom Coders]
+    D --> I[Build Tool Plugin]
+    D --> J[Dynamic Codable]
+
+    style A fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+### 1. Macro System
+The core of MetaCodable is built around Swift's macro system, primarily using:
+- `@Codable` - The main attribute macro that drives the code generation
+- `@CodedAt`, `@CodedIn`, `@CodedBy` etc. - Attribute macros for customizing coding behavior
+- `PluginCore` - Core functionality for macro expansions and code generation
+
+### 2. Helper Coders System
+Implements extensible coding strategies through:
+- `HelperCoder` protocol for custom coding implementations
+- Built-in coders like `ValueCoder`, `SequenceCoder`, etc.
+- Support for custom coders through `@CodedBy` attribute
+
+### 3. Protocol Generation System
+Provides dynamic protocol conformance through:
+- `MetaProtocolCodable` build tool plugin
+- `DynamicCodable` type for generating protocol implementations
+- Source code parsing and synthesis capabilities
+
+## Data Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Macros
+    participant CodeGen
+    participant Runtime
+
+    User->>Macros: Adds @Codable attribute
+    Macros->>CodeGen: Process attributes
+    CodeGen->>CodeGen: Generate implementation
+    CodeGen->>Runtime: Emit Codable conformance
+    Runtime->>User: Use generated code
+```
+
+## Key Features
+
+1. **Flexible Key Mapping**
+   - Custom CodingKey values per property
+   - Nested coding key support
+   - Multiple coding key paths
+
+2. **Smart Defaults and Error Handling**
+   - Default value specification
+   - Custom error handling
+   - Missing value handling
+
+3. **Protocol and Type Support**
+   - Enum support with various tagging styles
+   - Protocol type generation
+   - Generic type support
+
+## Implementation Details
+
+### Attribute Processing
+The framework processes attributes in multiple phases:
+1. Attribute validation and preprocessing
+2. Context gathering and analysis
+3. Code generation and emission
+
+### Code Generation
+The code generation system follows these principles:
+1. Maintains source compatibility
+2. Generates optimal, efficient code
+3. Supports full customization through attributes