> For the complete documentation index, see [llms.txt](https://bluebricks.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluebricks.co/docs/orchestration/bluebricks-git-repository-guide/git-repository-folder-structure.md).

# Git Repository Folder Structure

The following Git repository folder structure represents Bluebricks' best practice for managing infrastructure development using [Separation of Concerns (SoC)](/docs/orchestration/bluebricks-git-repository-guide.md#separation-of-concerns) principles.

```
.
├── bluebricks/                          # Bluebricks specific files
│   ├── blueprints/                      # Business logic implementations
│   │   ├── <blueprint_name>/
│   │   │   ├── bricks.json              # Blueprint definition
│   │   └── ...
│   ├── artifacts/                       # Reusable components
│   │   ├── <artifact_name>/
│   │   │   ├── bricks.json              # Artifact definition (metadata, dependencies, etc.)
│   │   │   ├── src/                     # Source code (e.g., Terraform, Helm charts, CloudFormation Stacks)
│   │   │   │   └── terraform/
│   │   │   │       ├── main.tf
│   │   │   │       ├── outputs.tf
│   │   │   │       └── variables.tf
│   │   └── ...
│   ├── environments/                    # Encapsulating folder for environment configuration 
│   │   ├── dev/
│   │   │   ├── <environment_name>.yaml   # Environment declarative file 
│   │   │   └── ...
│   │   ├── staging/
│   │   │   ├── <environment_name>.yaml   # Environment declarative file 
│   │   │   └── ...
│   │   ├── prod/
│   │   │   ├── <environment_name>.yaml   # Environment declarative file 
│   │   │   └── ...
```

## Explanation of Key Directories

* **`bluebricks/blueprints/`:** Contains the blueprints that define specific infrastructure or application environments. Each blueprint has its own directory and a `bricks.json` file defining its composition.
  * **`bricks.json` (Blueprint):** Defines the blueprint's name, description, version, and the Artifacts it uses.
* **`bluebricks/artifacts/`:** Contains reusable Artifacts that can be used across multiple blueprints. Each package has its own directory and a `bricks.json` file.
  * **`bricks.json` (Artifact):** Defines the package's metadata (name, description, version), dependencies on other artifacts, and any configurable properties.
  * **`src/`:** Contains the implementation of the package, typically using Infrastructure-as-Code tools like Terraform or Helm.
* **`environments/`:** Contains environment-specific configurations and manifests for deploying blueprints. This directory is used for GitOps pull-based environments to different environments.
  * **`<environment_name>.yaml`:** Declarative file for managing the configuration fed by a environment.

### `bricks.json` Structure (Examples)

Terraform AWS Launch Template Artifact:

`bluebricks/artifacts/terraform-aws-launch-template/bricks.json`

```
{
  "name": "terraform_aws_launch_template",
  "description": "Creates an AWS Launch Template.",
  "version": "1.2.0",
  "native": {
    "type": "terraform",
    "path": "./src/terraform"
  },
  "props": { /* ... */ },
  "outs": { /* ... */ }
}
```

AWS Launch Template Blueprint:

`bluebricks/blueprints/launch_template_s3/bricks.json`

```
{
  "name": "@bluebricks/launch_template_s3",
  "description": "EC2 Launch Template and S3 bucket.",
  "version": "1.2.0",
  "packages": [
    {
      "name": "random_output",
      "version": "1.0.4",
      "props": { /* ... */ }
    },
    {
      "name": "terraform_aws_launch_template",
      "version": "1.2.0", // Explicitly specifying the desired version
      "props": { /* ... */ }
    },
    {
      "name": "terraform_aws_s3_new",
      "version": "1.0.1",
      "props": { /* ... */ }
    }
  ],
  "props": { /* ... */ },
  "outs": { /* ... */ }
}
```