file_structure.md

DevFactory Files and Folder Structure

General Guidelines

This workspace is organized according to the following folders

/
├── .devcontainer/    # devcontainer configuration for GitHub Codespaces
├── .github/          # GitHub workflows and copilot reusable prompts
├── .vscode/          # VS Code workspace settings, including MCP servers
├── docs/             # Project documentation, guides, and architecture diagrams
│   ├── images/       # Images and diagrams used in documentation
│   └── plan/         # Implementation plans generated by GitHub Copilot
├── examples/         # Example Terraform configurations for different use cases
├── modules/          # Reusable Terraform modules for Azure resources
└── tests/            # Testing infrastructure for unit and integration tests
    ├── integration/  # Integration tests covering multi-module scenarios
    └── unit/         # Unit tests for individual modules
├── README.md         # Project overview, installation instructions, and usage guide.
└── *.tf              # Terraform root and module configuration files

In general, for each terraform module, the following files and folders MUST BE implemented:

• A root /<module_name_plural>.tf file. For example, a dev_center module will have a dev_centers.tf file at the root folder
• A new /modules/<module_name> folder. For example, /modules/dev_center, which contains:
  • module.tf
  • output.tf
  • variables.tf
  • README.md
• A new /tests/unit/<module_name> folder containing the files used for terraform test (according to the testing guidelines in #file:/docs/testing.md). For example, /tests/unit/dev_center, which contains a dev_center_test.tftest.hcl file
• A new examples/<module_name> folder containing an example implementation of the module. For example, /examples/dev_center which contains a configuration.tfvars file. If there are more than one example, these are separated by folder such as /examples/dev_center/simple_case/configuraiton.tfvars and /examples/dev_center/enhanced_case/configuraiton.tfvars
• A new input.devCenterExample example option in /.vscode/tasks.json

Specific Documentation

This section contains specific files/callouts. If the file is not explained here, see General Guidelines above.

Terraform Root Configuration Files

• provider.tf: Azure provider configuration using AzAPI v2.4.0 and azurecaf for naming conventions.
• variables.tf: Global variable definitions including global_settings for consistent naming patterns across all modules.
• resource_groups.tf: Root-level resource group orchestration, calling the resource group module for each defined resource group.

Terraform Module Configuration Files

• dev_centers.tf: Orchestrates Azure Dev Center creation using the dev_center module.
• dev_center_projects.tf: Manages Dev Center projects for organizing development resources.
• dev_center_catalogs.tf: Configures catalogs within Dev Centers for organizing DevBox templates.
• dev_center_dev_box_definitions.tf: Defines DevBox configurations with VM specifications and images.
• dev_center_environment_types.tf: Creates environment types for defining available development environments.
• dev_center_project_environment_types.tf: Associates environment types with Dev Center projects, enabling specific environment types within projects.
• dev_center_network_connections.tf: Establishes network connectivity between Dev Centers and virtual networks.
• dev_center_project_pools.tf: Manages pools of development resources within projects.
• dev_center_project_pool_schedules.tf: Configures scheduling for automated pool management and cost optimization.

docs/

• conventions.md: Comprehensive coding standards and conventions for Terraform development, including file organization, naming conventions, variable structure patterns, and best practices for consistent code across all modules.
• getting_started.md: Complete setup guide including prerequisites (Terraform, Azure CLI), authentication setup, GitHub Codespaces configuration with MCP (Model Context Protocol) server support, and step-by-step deployment instructions with both VS Code tasks and command-line options.
• file_structure.md: (This file) Documentation of the files and folder structure standards and overview of this workspace.
• module_guide.md: Detailed reference for each Terraform module including purpose, usage examples, input variables, configuration options, and inter-module relationships for Resource Groups, Dev Centers, Projects, Environment Types, Network Connections, Galleries, and Catalogs.
• testing.md: Comprehensive testing guide covering Terraform's native testing functionality with provider mocking, test structure (unit vs integration), running tests via VS Code tasks or command line, writing new tests following established patterns, troubleshooting common issues, and validation procedures.

docs/images/

• devfactoryv1.png: Visual diagram of the DevFactory architecture and component relationships.

docs/plan/

• Directory for implementation plans generated by GitHub Copilot.
• dev_center_environment_type.plan.md: Implementation plan for the Dev Center Environment Type module, outlining the structure and development steps required to create environment type resources within Dev Centers.

tests/

Comprehensive testing infrastructure using Terraform's native testing functionality with provider mocking.

tests/run_tests.sh

• run_tests.sh: Main test execution script that runs all unit and integration tests with colored output and status reporting.
• run_test.sh: Individual test runner script for executing specific module tests.

tests/integration/

• dev_center_integration_test.tftest.hcl: Integration tests validating interactions between multiple modules, ensuring proper resource relationships and data flow between Resource Groups, Dev Centers, Projects, and related components.

tests/unit/

Unit test directories for each module, containing isolated tests that validate individual module functionality without external dependencies.