Flutter-Structurizr: Instructions file for Codex

AGENTS.md - Flutter Structurizr for AI Agents

This document provides essential information for AI agents (like Codex) working with the Dart Structurizr codebase. It's specifically structured to help agents understand the repository organization, setup process, and development workflow in an offline environment.

Development Environment Setup

Offline Setup for Codex

The repository includes a complete Flutter SDK and all dependencies for offline development in Codex:

# Run this first when starting a new Codex session
./codex_offline_setup_split.sh

This script will:

1. Reassemble split archive files from .codex/ directory
2. Extract the complete Flutter SDK (704MB) and package cache (387MB)
3. Configure the environment for offline operation
4. Create wrappers for flutter and dart commands

Important: Use the Wrapper Commands

After setup, always use the wrapper commands to ensure offline operation:

# Use these wrapper commands
./flutter [command]  # Flutter commands
./dart [command]     # Dart commands

# Examples
./flutter pub get
./flutter test
./flutter analyze
./dart analyze

Troubleshooting Offline Setup

If you encounter issues with the offline setup:

# Check if setup completed successfully
test -f .codex_setup_complete && echo "Setup complete" || echo "Setup incomplete"

# Manually extract from archives if needed
cd .codex
cat flutter-sdk.tar.gz.part.* > flutter-sdk.tar.gz
tar -xzf flutter-sdk.tar.gz
cat pub-cache.tar.gz.part.* > pub-cache.tar.gz
tar -xzf pub-cache.tar.gz

Project Structure

Key Directories

lib/
  ├── domain/              # Pure Dart domain models
  │   ├── model/           # Core model elements (Person, SoftwareSystem, etc.)
  │   ├── view/            # View definitions (SystemContextView, etc.)
  │   ├── parser/          # DSL parser components (being refactored)
  │   ├── documentation/   # Documentation model
  │   └── style/           # Styling system
  ├── application/         # Use cases and business logic
  │   ├── workspace/       # Workspace management
  │   ├── dsl/             # DSL parsing
  │   └── command/         # Command pattern for undo/redo
  ├── infrastructure/      # External integrations
  │   ├── serialization/   # JSON serialization
  │   ├── persistence/     # File storage
  │   └── export/          # Export facilities
  ├── presentation/        # Flutter UI components
  │   ├── widgets/         # Reusable widgets
  │   ├── pages/           # Application pages
  │   ├── rendering/       # Canvas rendering
  │   └── layout/          # Layout algorithms

test/                      # Test suite
  ├── domain/              # Domain model tests
  ├── application/         # Application layer tests
  ├── infrastructure/      # Infrastructure tests
  ├── presentation/        # UI component tests
  └── integration/         # End-to-end tests

example/                   # Example applications
  └── lib/                 # Various example implementations