# RIO Infrastructure Guide

Use this guide when consuming `@rio-cloud/cdk-v2-constructs` from RIO CDK v2
infrastructure projects.

This guide covers infrastructure-specific structure and pipeline conventions.

## Recommended Structure

A typical RIO infrastructure package often uses a structure like:

- `bin/infrastructure.ts`: CDK app entrypoint and deployment environment.
- `lib/app-stack.ts`: runtime service resources and service monitoring.
- `lib/data-stack.ts`: stateful or shared data resources.
- `lib/pipeline-stack.ts`: trigger bucket sources, CodePipeline definitions,
  CodeBuild steps, deployment stages, and pipeline metadata.
- `test/`: synthesized template assertions.

## Infrastructure-Specific Usage

Use `rio.ClassifyPipelineType.apply(...)` with `rio.RioPipelineType.DEPLOY`,
`BRANCH`, or `VULNERABILITY` for pipeline metadata instead of manually
recreating equivalent tags.

Use `rio.TriggerKey.MASTER_REPO` and `rio.TriggerKey.BRANCH_REPO` for RIO
Bitbucket trigger bucket keys. Standard RIO pipelines use the imported
`bitbucket-integration-s3-bucket` trigger bucket and S3 source events.

## Pipeline Guardrails

Use the trigger bucket source pattern for standard RIO pipelines. Do not use
CodeStar Connections, GitHub source actions, `CodeStarConnectionsSourceAction`,
or `ConnectionArn` parameters unless the service intentionally needs a
non-standard pipeline.

Include the main deployment pipeline by default. Add branch and vulnerability
pipelines only when the project needs them or the user requests them.

Prefer the target project's current CodeBuild defaults for new pipeline code.
Fall back to another architecture or build image only when the project
toolchain requires it, and document that reason.

## Project Setup

When creating or extending a RIO infrastructure package, keep the project
layout intentional and replace any placeholder service names, account IDs,
build commands, and stack contents with project-specific values before
synthesis.

When using `node` or `npm` commands for this package, read the project's
`.nvmrc` or `package.json` to determine the expected Node.js version, and keep
`npm` aligned with the versions declared there. Align local development, CI,
and any generated pipeline steps with those project-specific settings.

If a project already has infrastructure, preserve its stack boundaries and
validation scripts unless the change explicitly updates them.