README

InsideApps Coding Standards & Guidelines Package for AI Assistants

Reusable coding standards and architectural guidelines for Symfony projects with AI-assisted development

Overview

DDD-IA-CONTEXT is a Composer package that automatically sets up comprehensive coding standards and architectural guidelines in your Symfony projects. It provides AI assistants with a complete reference for:

• Domain-Driven Design patterns (Entities, Value Objects, Repositories)
• Hexagonal Architecture implementation
• PHP 8.1+ best practices (strict types, named parameters, readonly properties)
• Symfony module creation workflows
• Testing standards (Unit, Integration, Acceptance)
• Zero-comment policy enforcement

When installed, the package copies all guidelines to your project's .insideapps/ folder, making them accessible to AI assistants without vendor directory access issues.

Installation

Install as a development dependency (recommended):

composer require --dev insideapps/ddd-iacontext

The package automatically:

1. Creates .insideapps/docs/ directory in your project root
2. Copies insideapps_guideline.md to .insideapps/docs/
3. Creates insideapps.md reference file in your project root

That's it! The guidelines are now available at .insideapps/docs/insideapps_guideline.md

What's Included

The Complete Guideline File

The insideapps_guideline.md file (318 lines, optimized for AI) includes:

🤖 AI Mandatory Rules

• Zero tolerance rules (NO COMMENTS, strict types, named parameters)
• Entity ID patterns (must extend GenericUuid)
• Value Object patterns (extend StringValue or standalone)
• Repository patterns (Domain interfaces + Infrastructure implementations)
• Test structure requirements

📦 Entity Pattern

• Complete entity structure with checklist (10 required components)
• Factory methods (create(), modify())
• Domain events (EntityWasCreated, EntityWasModified)
• Attributes trait pattern
• AuditFields integration

💎 Value Objects

• String value objects extending StringValue
• Integer/custom value objects
• Validation patterns
• Immutability rules

🗄️ Repositories

• Domain interface patterns
• Infrastructure implementation with AbstractDoctrineRepository
• Method patterns (findById, store, searchAll)
• Raw SQL query patterns for performance-critical operations

🏗️ Module Creation

• 6-step workflow with validation checklist
• Directory structure templates
• Configuration file patterns ({module}_services.yaml, {module}_twig.yaml)
• Composer autoload registration
• Route registration

🧪 Testing Standards

• Namespace structure (Tests\Unit\, Tests\Integration\)
• Base class requirements
• Group annotations
• Integration test patterns

Installation

Standard Installation

composer require insideapps/ddd-iacontext

Development Environment Installation

composer require --dev insideapps/ddd-iacontext

When installed as a dev dependency, the package will still set up all necessary files and directories, but won't be included in your production environment when using --no-dev flag during deployment.

Quick Start

For AI Assistants

After installation, AI assistants should read the complete guideline file first:

Read .insideapps/docs/insideapps_guideline.md

This file contains:

• ✅ Mandatory coding rules (NO COMMENTS, strict types, named parameters)
• ✅ Entity patterns with complete examples
• ✅ Value Object patterns (StringValue, standalone)
• ✅ Repository patterns (Domain interfaces, Infrastructure implementations)
• ✅ Module creation workflow (6-step process)
• ✅ Test structure (Unit, Integration, Acceptance)
• ✅ Doctrine mapping patterns
• ✅ Domain events implementation

Alternative Commands

You can also use these commands to load context:

insideapps:start

Or:

insideapps load context

Automatic Setup Process

The following happens automatically during installation:

1. .insideapps/ folder structure is created in your project root
2. insideapps_guideline.md is copied to .insideapps/docs/ - Complete coding standards (4000+ lines)
3. insideapps.md file is created in your project root - Quick reference for AI assistants
4. Memory system is initialized in .insideapps/memory/ for tracking changes
5. Protocol files are created in .insideapps/protocols/ for AI workflow guidance

Alternative: Via Direct Command

insideapps:start

I'm working with a project that uses the insideapps/ddd-iacontext package. Before proceeding:

1. Check if the vendor/insideapps/ddd-iacontext package exists in my project
2. If it exists, first read .insideapps/docs/AI_QUICKSTART.md for a quick overview
3. Then explore these key files to understand our architecture:
   - .insideapps/docs/engineering/general-context.md
   - .insideapps/docs/engineering/entity-creation-rules.md
   - .insideapps/docs/engineering/module-creation-rules.md
4. Also read the business rules in the business-context/ directory
5. For any code you generate, strictly follow the architectural patterns and business rules
6. Remember this context for our entire conversation

My current task is: [DESCRIBE YOUR TASK HERE]

Usage Examples

Tell AI to Follow the Guidelines

Read .insideapps/docs/insideapps_guideline.md and follow all coding standards.

Create a Module

Create a new module called "Sales" following the 6-step module creation workflow 
from the guideline file.

Create an Entity

Create a Customer entity with CustomerId, CustomerName, and CustomerEmail properties.
Follow the entity pattern from the guideline file, including:
- Entity class (NOT final)
- EntityId extending GenericUuid
- EntityAttributes trait
- Value Objects extending StringValue
- CustomerWasCreated and CustomerWasModified events
- CustomerCommand interface
- CustomerRepository domain interface
- CustomerDcmRepository infrastructure implementation

Create a Repository

Create a CourseRepository following the repository pattern from the guideline file.
Include both the domain interface and the infrastructure implementation extending 
AbstractDoctrineRepository.

Features

Comprehensive Coding Standards

• 4000+ lines of detailed patterns and examples
• Entity patterns with complete checklists
• Value Object patterns for strings and custom types
• Repository patterns with domain and infrastructure layers
• Module creation 6-step workflow
• Test structure requirements and examples

AI-Friendly Format

• Markdown format for easy parsing
• Code examples for every pattern
• Checklists for validation
• Common mistakes highlighted
• Quick reference tables

Additional Features

Memory System

AI assistants can track changes between sessions:

• General memory: .insideapps/memory/general.md - Project context
• Daily logs: .insideapps/memory/logs/YYYY-MM-DD.md - Change tracking

Protocol Files

AI workflow guidance:

• AI Protocol: .insideapps/protocols/ai-protocol.md - Interpretation rules
• Self-Evaluation: .insideapps/protocols/self-evaluation.md - Quality checks

Why This Package?

Problem: Vendor Directory Access

AI assistants cannot access files in the vendor/ directory due to gitignore restrictions, making it impossible to share coding standards across projects.

Solution: Automatic Copying

This package automatically copies insideapps_guideline.md from the package's src/ folder to your project's .insideapps/docs/ folder during installation.

Benefits

• ✅ Reusable standards across all your projects
• ✅ Single source of truth maintained in the package
• ✅ AI-accessible guidelines without permission issues
• ✅ Version controlled standards that update with the package
• ✅ Consistent code quality across your entire organization

Key Coding Standards

The guideline file enforces these mandatory rules:

Zero Tolerance Rules

1. ❌ NO COMMENTS - No docblocks, inline comments, or multi-line comments
2. ✅ declare(strict_types=1); - First line after <?php in EVERY file
3. ✅ Named Parameters - MANDATORY for all method calls with 2+ parameters
4. ✅ Final Classes - Services, repositories, controllers, value objects
5. ✅ Entity IDs - MUST extend Shared\Domain\ValueObject\GenericUuid
6. ✅ Value Objects - MUST extend StringValue (for strings) or standalone
7. ✅ Relationships - Inject ENTIRE entity (NOT ID): Course $course
8. ✅ AuditFields - Use AuditFields::create() and withModification()
9. ✅ Domain Events - Public readonly properties, name() method, const NAME
10. ❌ NO Mocks in Integration Tests - Use real commands via $this->getService()

Test Structure

• Domain tests: Tests\Unit\{Module}\Domain\ with @group unit
• Application tests: Tests\Application\UseCase\ extending AbstractIntegrationTest
• Repository tests: Tests\Infrastructure\...\Repository\ extending AbstractIntegrationTest

Repository Pattern

• Domain interfaces: findById{Entity}() throws NotFoundException, store() returns entity
• Infrastructure: Extend AbstractDoctrineRepository, use $this->objectRepository->findBy()

Project Structure After Installation

your-project/
├── .insideapps/
│   ├── docs/
│   │   └── insideapps_guideline.md    # Complete coding standards (4000+ lines)
│   ├── memory/
│   │   ├── general.md                  # General project memory
│   │   └── logs/                       # Date-stamped change logs
│   └── protocols/
│       ├── ai-protocol.md              # AI interpretation protocol
│       └── self-evaluation.md          # AI self-evaluation protocol
├── insideapps.md                       # Quick reference for AI assistants
└── composer.json                       # Package is listed in require/require-dev

Getting Started

Step 1: Install the Package

composer require insideapps/ddd-iacontext

Step 2: Verify Installation

Check that the following have been created:

• ✅ .insideapps/docs/insideapps_guideline.md - Complete coding standards
• ✅ insideapps.md in your project root - Quick reference
• ✅ .insideapps/memory/ - Memory system for AI assistants
• ✅ .insideapps/protocols/ - AI workflow protocols

Step 3: Instruct Your AI Assistant

Tell your AI assistant to read the guideline file:

Please read .insideapps/docs/insideapps_guideline.md and follow all the coding standards defined there.

Step 4: Start Coding

Use the patterns from the guideline file:

Create a new module called "Sales" following the module creation workflow in the guideline file.

or

Create a Customer entity with name and email properties, following the entity pattern in the guideline file.

Step 5: Maintain Standards

The guideline file is your single source of truth. When you update the package, the latest standards are automatically copied to your project.

Real-World Example

Before Installation

// Inconsistent code across projects
class Customer {
    /** @var string */  // ❌ Comments not allowed
    private $name;      // ❌ No type hints
    
    public function getName() {
        return $this->name;
    }
}

After Installation

// Following insideapps_guideline.md standards
declare(strict_types=1);

class Customer
{
    use CustomerAttributes;
    
    private function __construct(
        protected readonly CustomerId $idCustomer,
        protected CustomerName $name,
        protected AuditFields $auditFields
    ) {}
    
    public static function create(CustomerCommand $command): self
    {
        $customer = new self(
            idCustomer: CustomerId::generate(),
            name: CustomerName::create(value: $command->name()),
            auditFields: AuditFields::create()
        );
        
        DomainEvent::raise(
            event: new CustomerWasCreated(
                idCustomer: $customer->idCustomer->valueId()
            )
        );
        
        return $customer;
    }
}

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

2025 InsideApps. All rights reserved.

InsideApps • Documentation • GitHub