> ## Documentation Index
>
> Fetch the complete documentation index at: https://superpowers.frontis.nl/llms.txt
> Use this file to discover all available pages before exploring further.

---

title: Frontis conventions
summary: How to read and apply Frontis local convention files for project identity, canonical naming, directory layout, Azure DevOps pipeline filenames, Azure resources, and validation.
order: 20

---

# Frontis conventions

Use this guide when working with Frontis repository conventions.

This document explains how agents should read and apply the local `.frontis` convention files. It does not replace those files. The local repository files remain the source of truth for each project.

## Core rule

Before changing naming, repository structure, namespaces, project files, Azure resources, pipelines, deployment settings, or agent instructions, read the local convention files first.

Required files:

```text
.frontis/project.json
.frontis/project-context.yaml
.frontis/naming-convention.yaml
.frontis/azure-conventions.yaml
```

Priority order:

1. explicit user instruction;
2. local repository files;
3. Frontis online agent documentation;
4. general agent knowledge.

Do not invent Frontis conventions from memory.

## What each file means

### `.frontis/project.json`

Concrete project instance values.

This file contains the actual project identity used by the repository.

Typical fields:

```json
{
  "schemaVersion": "1.0.0",
  "company": "AALP",
  "product": "CompositePIM",
  "component": "Api",
  "hosting": "dedicated",
  "environments": ["test", "prod"],
  "grippNumber": 2600173,
  "team": "Everest"
}
```

Agents must use this file to derive:

- canonical project name;
- repository name;
- root namespace or module name;
- local clone path;
- Azure DevOps project;
- pipeline filenames;
- Azure resource names;
- default tags;
- environment-specific resources.

Do not add secrets, Azure subscription IDs, connection strings, passwords, API keys, or customer credentials to this file.

### `.frontis/project-context.yaml`

Schema and validation rules for project context variables.

This file defines variable names, required fields, casing rules, allowed mappings, examples, cross-variable constraints, and precedence.

It is schema-only. Concrete values belong in `.frontis/project.json`.

### `.frontis/naming-convention.yaml`

Canonical naming rules.

This file defines:

- project naming pattern;
- validation rules;
- artifact alignment;
- test naming;
- local directory layout;
- Azure DevOps project mapping;
- pipeline YAML filename rules;
- valid and invalid examples.

Use this file whenever creating or changing:

- repository names;
- solution or workspace names;
- root namespaces;
- project names;
- package names;
- test project names;
- local clone paths;
- pipeline filenames.

### `.frontis/azure-conventions.yaml`

Azure resource naming and hosting rules.

Use this file whenever creating or changing:

- resource groups;
- storage accounts;
- blob containers;
- Log Analytics workspaces;
- Application Insights resources;
- App Services;
- App Service Plans;
- SQL servers;
- SQL databases;
- SQL firewall rules;
- Azure tags;
- hosting-specific provisioning behavior.

This file is not the source of truth for pipeline content or build/release structure. It governs Azure resources, defaults, tags, constraints, and hosting-specific provisioning rules.

## Project context variables

The following values are required for a normal Frontis project.

| Variable       |    Type | Rule                    | Meaning                                                              |
| -------------- | ------: | ----------------------- | -------------------------------------------------------------------- |
| `company`      |  string | registered casing       | Owning organisation or customer. Also maps to Azure DevOps project.  |
| `product`      |  string | PascalCase              | Product or product line.                                             |
| `component`    |  string | PascalCase              | Specific deliverable or module. Must describe purpose.               |
| `hosting`      |  string | exact match             | Hosting model: usually `dedicated` or `shared`.                      |
| `environments` |   array | lowercase               | OTAP environment abbreviations such as `dev`, `test`, `acc`, `prod`. |
| `grippNumber`  | integer | numeric                 | Customer number in Gripp.                                            |
| `team`         |  string | exact team abbreviation | Implementing team, for example `Everest` or `Quack`.                 |

Rules:

- `company` uses registered casing and is not forced to PascalCase.
- `product` must use PascalCase.
- `component` must use PascalCase.
- `component` must describe what it does.
- Generic components such as `Helpers`, `Common`, `Utilities`, `Misc`, `Shared`, and `General` are not valid component names.
- `hosting` is case-sensitive.
- `environments` are case-sensitive and lowercase.
- `team` is case-sensitive.
- If `hosting` is `shared`, the environments array may contain only `prod`.

## Canonical project name

The canonical project name uses this pattern:

```text
{company}.{product}.{component}
```

Example:

```text
AALP.CompositePIM.Api
```

Allowed optional extension:

```text
{company}.{product}.{component}.{sub_component}
```

Use a fourth segment only when the component is large enough to require independent packaging and governance approval exists.

Validation rules:

- minimum 3 segments;
- maximum 4 segments;
- separator is a dot;
- no hyphens;
- no underscores;
- no embedded version numbers such as `ApiV2`;
- product, component, and sub-component use PascalCase;
- company uses registered casing;
- component must not be generic.

Valid examples:

```text
AALP.ProductInformationSystem.Api
AALP.Corporate.UmbracoWebsite
FrontisRAD.Conventions.Naming
FrontisRAD.Conventions.Naming.Validation
```

Invalid examples:

```text
Frontis.Api
frontis.webportal.api
Frontis-WebPortal-Api
Frontis.WebPortal.ApiV2
Frontis.WebPortal.Helpers
```

## Artifact alignment

All project-level artifacts must share the canonical base name.

For `.NET` projects, this usually means the following should align:

```text
repository name
solution name
project name
root namespace
assembly name
package identifier
build output name
```

For frontend or Nuxt projects, apply the same principle to the relevant artifacts:

```text
repository name
workspace name
package name
module name
build artifact name
```

Do not create unrelated names for the same project.

Example for canonical name:

```text
AALP.CompositePIM.Api
```

Expected aligned artifacts:

```text
AALP.CompositePIM.Api
AALP.CompositePIM.Api.sln
AALP.CompositePIM.Api.csproj
namespace AALP.CompositePIM.Api
```

## Test naming

Test artifacts append a test-type suffix to the canonical name.

Default `.NET` examples:

```text
AALP.CompositePIM.Api.Tests
AALP.CompositePIM.Api.Tests.Integration
```

Rules:

- unit tests use `.Tests` by default;
- integration tests use `.Tests.Integration` by default;
- adapt to the technology when needed;
- keep the canonical project name intact;
- do not create vague test project names such as `Tests`, `ApiTests`, or `Common.Tests` when a canonical name is available.

## Local directory layout

Frontis developer machines use this root:

```text
P:\Git
```

Repository clone path pattern:

```text
P:\Git\{company}\{canonical_name}
```

Example:

```text
P:\Git\AALP\AALP.CompositePIM.Api
```

Rules:

- the `company` segment maps to the Azure DevOps project name;
- the folder directly under `P:\Git` is the Azure DevOps project name;
- the repository folder name must be the canonical project name;
- do not rename the repository folder after cloning;
- do not create deeper nesting.

## Azure DevOps project mapping

The `company` segment maps to the Azure DevOps project.

Example:

```text
company: AALP
canonical_name: AALP.CompositePIM.Api
Azure DevOps project: AALP
local path: P:\Git\AALP\AALP.CompositePIM.Api
```

Agents must use this mapping when generating clone paths, documentation, onboarding steps, and repository references.

## Pipeline filename convention

Azure DevOps multi-stage pipeline filenames use this pattern:

```text
{company}-{product}-{component}-{pipeline_type}-{hosting_variant}.yml
```

Where:

| Segment           | Allowed values              | Rule              |
| ----------------- | --------------------------- | ----------------- |
| `company`         | from canonical project name | registered casing |
| `product`         | from canonical project name | PascalCase        |
| `component`       | from canonical project name | PascalCase        |
| `pipeline_type`   | `infra`, `release`          | lowercase         |
| `hosting_variant` | `shared`, `dedicated`       | lowercase         |

Pipeline types:

```text
infra    = infrastructure provisioning
release  = build, test, package and deploy
```

Hosting variants:

```text
shared     = shared hosting plan or shared infrastructure target
dedicated  = dedicated project-specific hosting
```

Rules:

- exactly 5 hyphen-separated segments before the extension;
- extension must be `.yml`;
- do not use `.yaml`;
- do not use generic names such as `build.yml` or `deploy.yml`;
- do not use dots as segment separators;
- `pipeline_type` must be `infra` or `release`;
- `hosting_variant` must be `shared` or `dedicated`;
- the first 3 segments must match the canonical project identity and casing.

Valid examples:

```text
AALP-ProductInformationSystem-Api-infra-shared.yml
AALP-ProductInformationSystem-Api-release-shared.yml
AALP-Corporate-UmbracoWebsite-infra-dedicated.yml
AALP-Corporate-UmbracoWebsite-release-dedicated.yml
FrontisRAD-Conventions-Naming-release-shared.yml
```

Invalid examples:

```text
build.yml
my-deploy.yaml
AALP.ProductInformationSystem.Api.infra.shared.yml
AALP-ProductInformationSystem-Api-deploy-shared.yml
AALP-ProductInformationSystem-Api-infra-premium.yml
AALP-ProductInformationSystem-Api-infra.yml
aalp-productinformationsystem-api-infra-shared.yml
AALP-ProductInformationSystem-Api-Infra-Shared.yml
```

## Azure environment conventions

Azure environment abbreviations:

| Environment | Azure deployed | Tier    | Meaning                                     |
| ----------- | -------------: | ------- | ------------------------------------------- |
| `dev`       |             no | local   | Local development only. No Azure resources. |
| `test`      |            yes | nonprod | Test environment.                           |
| `acc`       |            yes | nonprod | Acceptance environment.                     |
| `prod`      |            yes | prod    | Production environment.                     |

Environment tiers:

```text
nonprod = test, acc
prod    = prod
```

Shared hosting constraint:

```text
hosting = shared -> environments = ["prod"]
```

Dedicated hosting can use additional OTAP environments where the project requires them.

## Azure global defaults

Unless overridden by `.frontis/azure-conventions.yaml`, Azure defaults are:

```text
location: germanywestcentral
constraint_violation_strategy: error_reject
```

Required tags:

| Tag           | Source                                        |
| ------------- | --------------------------------------------- |
| `project`     | computed as `{company}.{product}.{component}` |
| `environment` | environment token                             |
| `team`        | team token                                    |
| `customer`    | company token                                 |

Agents must include required tags when creating Azure resources or infrastructure-as-code.

## Azure resource naming patterns

Read `.frontis/azure-conventions.yaml` for full Azure constraints, lengths, allowed characters, defaults, hosting behavior, and exceptions.

Summary of common resource patterns:

| Resource type           | Pattern                                                           |
| ----------------------- | ----------------------------------------------------------------- |
| Resource Group          | `rg-{company}-{product}-{component}-{environment}`                |
| Storage Account         | `st{company}{product}{component}{environment}`                    |
| Blob Container          | `{container_name}`                                                |
| Log Analytics Workspace | `log-{company}-{product}-{component}-{environment}`               |
| Application Insights    | `appi-{company}-{product}-{component}-{environment}`              |
| App Service             | `app-{company}-{product}-{component}-{environment}`               |
| App Service Plan        | `plan-{company}-{product}-{component}-{environment}`              |
| SQL Server              | `sql-{company}-{product}-{component}-{environment}`               |
| SQL Database            | `sqldb-{company}-{product}-{component}-{environment}`             |
| SQL Firewall Rule       | `sqlfw-{company}-{product}-{component}-{environment}-{rule_name}` |

Important Azure rules:

- Azure platform constraints have the highest priority.
- Storage account names must be lowercase letters and numbers only, globally unique, and maximum 24 characters.
- App Service names are globally unique through `.azurewebsites.net`.
- Blob container names must be lowercase and may contain hyphens, but not consecutive hyphens.
- SQL Server names are globally unique and must not start or end with a hyphen.
- Application Insights names must not end with a space or period.
- Resource Group names must not end with a period.

When a generated resource name violates Azure constraints, do not guess a workaround. Stop and report the constraint problem.

## Azure hosting behavior

Dedicated hosting generally creates project-specific resources.

Shared hosting may reference existing shared infrastructure for some resource types.

Known shared infrastructure reference:

```text
azshared01-2024
```

Typical behavior:

| Resource type           | Dedicated | Shared                                   |
| ----------------------- | --------- | ---------------------------------------- |
| Resource Group          | create    | create                                   |
| Storage Account         | create    | create                                   |
| Blob Container          | create    | create                                   |
| Log Analytics Workspace | create    | create                                   |
| Application Insights    | create    | create                                   |
| App Service             | create    | create                                   |
| App Service Plan        | create    | reference existing shared infrastructure |
| SQL Server              | create    | reference existing shared infrastructure |
| SQL Database            | create    | create                                   |
| SQL Firewall Rule       | create    | create                                   |

Always read `.frontis/azure-conventions.yaml` before generating Azure infrastructure.

## Azure deployment slots

For App Services:

```text
enabled environment: prod
slot name: preproduction
hosting model: dedicated
```

Do not assume deployment slots exist for shared hosting or non-production environments unless the local Azure convention file says so.

## Azure precedence

When resolving Azure rules, apply this order:

1. Azure platform constraints;
2. explicit exceptions;
3. environment overrides;
4. hosting type defaults;
5. global defaults.

If there is a conflict, the higher tier wins.

## Out of scope for Azure conventions

The Azure convention file does not govern everything.

Do not use `.frontis/azure-conventions.yaml` as the source of truth for:

- Key Vaults;
- Virtual Networks;
- Front Doors;
- Container Registries;
- pipeline content and stages;
- build pipeline generation.

Use specific project documentation or ask the user when these are needed.

## Agent workflow when applying conventions

Before editing files, agents should summarize the effective context.

Example:

```text
Project context:
- company: AALP
- product: CompositePIM
- component: Api
- canonical name: AALP.CompositePIM.Api
- hosting: dedicated
- environments: test, prod
- team: Everest
- GRIPP number: 2600173

Derived values:
- local path: P:\Git\AALP\AALP.CompositePIM.Api
- release pipeline: AALP-CompositePIM-Api-release-dedicated.yml
- infra pipeline: AALP-CompositePIM-Api-infra-dedicated.yml
```

Then produce a short plan before creating or changing files.

## When to ask the user

Ask the user when:

- required project values are missing;
- a component name appears generic;
- a fourth canonical name segment is needed;
- shared hosting is requested with non-production environments;
- a generated Azure resource name violates Azure constraints;
- the requested resource type is out of scope;
- an existing convention file would be overwritten;
- a destructive Azure, pipeline, or repository change is requested.

## Do not do these things

Do not:

- create names from memory;
- rename repositories without approval;
- create generic pipeline filenames;
- use `.yaml` for pipeline files when the convention requires `.yml`;
- embed version numbers in canonical names;
- add secrets to `.frontis` files;
- create Azure resource names without reading `.frontis/azure-conventions.yaml`;
- claim compliance without validating against the local files;
- use online examples to override local repository values.

## Recommended validation checklist

After applying conventions, validate:

```text
[ ] .frontis/project.json exists and contains concrete values
[ ] .frontis/project-context.yaml exists
[ ] .frontis/naming-convention.yaml exists
[ ] .frontis/azure-conventions.yaml exists when Azure is involved
[ ] canonical project name follows {company}.{product}.{component}
[ ] repository name matches canonical project name
[ ] solution/workspace/project/package names are aligned
[ ] test names use canonical suffixes
[ ] local path follows P:\Git\{company}\{canonical_name}
[ ] pipeline filenames follow {company}-{product}-{component}-{pipeline_type}-{hosting_variant}.yml
[ ] Azure resource names follow the Azure convention file
[ ] required Azure tags are present
[ ] shared hosting constraints are respected
[ ] no secrets are committed
```

## Recommended prompt for agents

Use this prompt when asking an agent to apply conventions:

```text
Read AGENTS.md.
Read .frontis/project.json.
Read .frontis/project-context.yaml.
Read .frontis/naming-convention.yaml.
Read .frontis/azure-conventions.yaml if Azure, hosting, pipelines, infrastructure or deployment are involved.

Summarize the effective Frontis project context and derived names before editing files.
Do not invent conventions from memory.
Do not overwrite existing convention files without approval.
```

## Completion summary format

After applying conventions, respond with:

```text
Effective context:
- ...

Created:
- ...

Updated:
- ...

Skipped:
- ...

Validation:
- ...

Open questions:
- ...
```