Naamgeving van softwareoplossingen, repositories en omgevingen¶

Doel¶

Binnen onze organisatie ontwikkelen en beheren we onder andere:

websites;
webportalen;
webapplicaties;
integraties;
API's;
technische services.

Historisch werd iedere Git-repository een omgeving genoemd. Dit is technisch en organisatorisch onjuist.

Omgeving is geen synoniem voor repository

De term omgeving wordt uitsluitend gebruikt voor een context waarin software wordt ontwikkeld, getest of uitgevoerd, zoals:

local;
development;
test;
acceptatie;
staging;
productie.

Een Git-repository is geen omgeving.

Dit document definieert de begrippen en naamgevingsregels die binnen onze organisatie gebruikt moeten worden.

Kernbegrippen¶

De volgende begrippen worden organisatiebreed gehanteerd:

Begrip	Betekenis
Softwareoplossing	Het functionele geheel dat wij voor een klant ontwikkelen en beheren
Type	De classificatie van een softwareoplossing, zoals website, webportaal, webapplicatie of integratie
Applicatie	Een zelfstandig functionerend softwareonderdeel
Component	Een technisch onderdeel van een grotere softwareoplossing
Service	Een zelfstandig uitvoerbaar technisch proces zonder primaire gebruikersinterface
Repository	Een Git-repository waarin broncode en bijbehorende bestanden worden beheerd
Deployment	Een uitgerolde en uitvoerbare instantie van een applicatie, component of service
Omgeving	De context waarin een deployment draait, zoals acceptatie of productie
Project	Een tijdelijk traject waarin een softwareoplossing wordt gerealiseerd of gewijzigd
Systeem	Een bestaand intern of extern informatiesysteem, zoals een ERP, CRM of boekhoudpakket

1. Softwareoplossing¶

Definitie¶

Een softwareoplossing is het functionele geheel dat wij voor een klant ontwikkelen, leveren en beheren. Dit is het primaire object waarmee software binnen de organisatie en documentatie wordt aangeduid.

Voorbeelden:

Orderinvoer Van Rijn Coating
Employee Purchase Portal iUsed
Productkoppeling ThysToys
Corporate website Beumer Packaging
Brekz Checkout

Een softwareoplossing kan bestaan uit:

één of meerdere applicaties;
één of meerdere componenten;
één of meerdere integraties;
één of meerdere repositories;
één of meerdere deployments;
meerdere omgevingen.

Gebruik¶

Gebruik softwareoplossing als overkoepelende term in:

klantdocumentatie;
interne documentatie;
CRM;
ClickUp;
SLA-documentatie;
beheerprocessen;
technische inventarisaties;
architectuurbeschrijvingen.

Wanneer de context duidelijk is, mag de term worden verkort tot oplossing.

Voorbeeld¶

name: Orderinvoer Van Rijn Coating
type: web-application
customer: Van Rijn Coating
status: active

2. Type softwareoplossing¶

Iedere softwareoplossing krijgt een expliciet type.

Ondersteunde typen¶

Type	Technische waarde	Definitie
Website	`website`	Publiek toegankelijke en hoofdzakelijk contentgerichte toepassing
Webportaal	`web-portal`	Afgeschermde toepassing voor klanten, medewerkers, leveranciers of partners
Webapplicatie	`web-application`	Interactieve toepassing die een bedrijfsproces ondersteunt
Integratie	`integration`	Geautomatiseerde gegevensuitwisseling tussen twee of meer systemen
API	`api`	Zelfstandig aangeboden technische interface
Service	`service`	Zelfstandig uitvoerbaar technisch proces zonder primaire gebruikersinterface

Classificatieregels¶

Website Webportaal Webapplicatie Integratie API Service

Gebruik website wanneer:

de toepassing hoofdzakelijk publieke content toont;
bezoekers meestal niet hoeven in te loggen;
contentpublicatie het primaire doel is.

Gebruik webportaal wanneer:

gebruikers moeten inloggen;
de toepassing bedoeld is voor een specifieke gebruikersgroep;
de gebruiker toegang krijgt tot persoonlijke, klant- of bedrijfsgegevens.

Gebruik webapplicatie wanneer:

gebruikers actief bedrijfsprocessen uitvoeren;
de toepassing meer is dan alleen informatievoorziening;
functionaliteit, workflows en gegevensverwerking centraal staan.

Gebruik integratie wanneer:

de software primair gegevens uitwisselt tussen systemen;
er geen primaire gebruikersinterface aanwezig is;
synchronisatie, import, export of eventverwerking het hoofddoel is.

Gebruik API wanneer:

de technische interface zelfstandig wordt aangeboden;
meerdere applicaties of systemen de interface gebruiken;
de API een eigen verantwoordelijkheid en lifecycle heeft.

Gebruik service wanneer:

de software zelfstandig draait;
de software bijvoorbeeld achtergrondtaken, verwerking of automatisering uitvoert;
er geen primaire gebruikersinterface aanwezig is.

3. Applicatie en component¶

Applicatie¶

Een applicatie is een zelfstandig functionerend onderdeel met een duidelijke functionele verantwoordelijkheid.

Voorbeelden:

Checkout frontend
Orderbeheerportaal
Productbeheerapplicatie
Klantenportaal
REST API

Een applicatie kan:

een eigen repository hebben;
onderdeel zijn van een monorepository;
zelfstandig worden gedeployed;
op meerdere omgevingen draaien.

Component¶

Een component is een technisch onderdeel van een grotere softwareoplossing.

Voorbeelden:

frontend;
backend;
API;
worker;
webhook handler;
queue consumer;
importservice;
exportservice;
authenticatieservice.

Gebruik component voornamelijk in technische documentatie. Voor functionele of klantgerichte communicatie heeft applicatie of het specifieke type meestal de voorkeur.

Voorbeeld¶

Softwareoplossing: Brekz Checkout
Componenten:
- Checkout frontend
- Checkout API
- Payment webhook service
- Order export integratie

4. Repository¶

Definitie¶

Een repository is een Git-repository waarin broncode, configuratie, documentatie en andere projectbestanden worden beheerd.

Gebruik de termen:

repository;
Git-repository;
code repository.

Gebruik nooit

Gebruik nooit omgeving als synoniem voor repository.

Belangrijk onderscheid¶

Een repository is niet automatisch:

een softwareoplossing;
een applicatie;
een component;
een deployment;
een omgeving;
een project.

Een softwareoplossing kan meerdere repositories bevatten. Een repository kan ook meerdere applicaties of componenten bevatten, bijvoorbeeld bij een monorepository.

Voorbeelden¶

flooris/brekz-checkout
flooris/brekz-checkout-frontend
flooris/brekz-exact-export

Documentatievoorbeeld¶

repositories:
  - name: Checkout backend
    url: github.com/flooris/brekz-checkout
  - name: Checkout frontend
    url: github.com/flooris/brekz-checkout-frontend

5. Deployment¶

Definitie¶

Een deployment is een uitgerolde en uitvoerbare instantie van een applicatie, component of service.

Een deployment verbindt de software met:

een omgeving;
infrastructuur;
configuratie;
domeinnamen;
databases;
externe services;
een specifieke softwareversie.

Voorbeeld¶

Applicatie: Employee Purchase Portal
Deployment: iused-employee-portal-production
Omgeving: productie
Server: app-03

Wanneer deployment expliciet vastleggen¶

Leg deployments expliciet vast wanneer:

dezelfde applicatie voor meerdere klanten wordt uitgerold;
dezelfde applicatie meerdere instanties heeft;
er meerdere landen of labels zijn;
software multi-tenant of single-tenant kan worden ingezet;
verschillende deployments afwijkende configuraties hebben;
infrastructuurbeheer onderdeel is van de documentatie.

6. Omgeving¶

Definitie¶

Een omgeving is de context waarin software wordt ontwikkeld, getest, geaccepteerd of gebruikt. De term omgeving mag alleen hiervoor worden gebruikt.

Standaardomgevingen¶

Omgeving	Technische waarde	Doel
Local	`local`	Ontwikkeling op de lokale werkplek van een developer
Development	`development`	Gedeelde ontwikkelomgeving
Test	`test`	Technisch en functioneel testen
Acceptatie	`acceptance`	Acceptatie door klant, product owner of interne verantwoordelijke
Staging	`staging`	Productieachtige omgeving voor deploymentvalidatie
Productie	`production`	Daadwerkelijk gebruik door eindgebruikers

Gebruik van development¶

Een gedeelde developmentomgeving is optioneel. Gebruik deze alleen wanneer daar een concreet doel voor bestaat, bijvoorbeeld:

integratietesten tussen meerdere ontwikkelaars;
testen met gedeelde externe systemen;
demonstreren van werk in uitvoering.

Verschil tussen test, acceptatie en staging¶

Test Acceptatie Staging

Bedoeld voor:

functionele tests;
technische tests;
QA;
geautomatiseerde tests;
experimentele configuraties.

Bedoeld voor:

beoordeling door klant of product owner;
gebruikersacceptatietesten;
goedkeuring van opgeleverde functionaliteit.

Bedoeld voor:

valideren van een release vóór productie;
testen van deploymentprocedures;
productieachtige infrastructuur en configuratie;
smoke tests vóór livegang.

Acceptatie en staging combineren

Gebruik acceptatie en staging alleen als beide omgevingen een duidelijk verschillend doel hebben.

Voorbeeld¶

environments:
  acceptance:
    url: https://acceptatie.orders.example.nl
  production:
    url: https://orders.example.nl

7. Project¶

Definitie¶

Een project is een tijdelijk traject waarin een softwareoplossing wordt gerealiseerd, uitgebreid, gemigreerd of gewijzigd.

Een project heeft doorgaans:

een begin;
een eind;
een doel;
een scope;
een planning;
een budget;
betrokken personen.

Een softwareoplossing blijft na afronding van een project bestaan.

Voorbeeld¶

Project: Implementatie Orderinvoer 2026
Softwareoplossing: Orderinvoer Van Rijn Coating

Rond één softwareoplossing kunnen meerdere projecten plaatsvinden. Voorbeelden:

eerste realisatie;
redesign;
Laravel-upgrade;
migratie naar nieuwe infrastructuur;
toevoeging van een nieuwe integratie;
performanceverbetering;
security-update.

Project is geen permanente naam

Gebruik project daarom niet als permanente naam voor een softwareoplossing.

8. Product¶

Gebruik de term softwareproduct alleen wanneer de software daadwerkelijk als product wordt ontwikkeld en beheerd.

Kenmerken van een softwareproduct zijn bijvoorbeeld:

meerdere klanten gebruiken dezelfde oplossing;
er is een eigen roadmap;
er is centraal product ownership;
er bestaat versiebeleid;
functionaliteit wordt generiek ontwikkeld;
releases zijn niet uitsluitend gekoppeld aan één klantproject.

Voor klantspecifiek maatwerk heeft de term softwareoplossing de voorkeur.

9. Systeem¶

De term systeem is breed en kan verwarring veroorzaken.

Een systeem kan namelijk verwijzen naar:

een ERP-systeem;
een CRM-systeem;
een extern platform;
een server;
infrastructuur;
een softwareoplossing;
een compleet IT-landschap.

Gebruik systeem voornamelijk voor bestaande interne of externe informatiesystemen.

Voorbeeld:

Bronsysteem: FileMaker
Doelsysteem: Exact Online
Integratie: FileMaker–Exact orderintegratie

Gebruik voor onze eigen software bij voorkeur de preciezere begrippen:

softwareoplossing;
applicatie;
component;
service;
integratie.

10. Begrippenstructuur¶

Hanteer waar relevant de volgende hiërarchie:

Klant
└── Softwareoplossing
    ├── Applicatie of component
    │   ├── Repository
    │   └── Deployment
    │       └── Omgeving
    ├── Applicatie of component
    │   ├── Repository
    │   └── Deployment
    │       └── Omgeving
    └── Integratie
        ├── Repository
        └── Deployment
            └── Omgeving

Deze structuur hoeft niet altijd volledig te worden vastgelegd. Voor een eenvoudige website kan de structuur bijvoorbeeld zijn:

Klant
└── Softwareoplossing: Corporate website
    ├── Repository
    └── Omgevingen
        ├── Acceptatie
        └── Productie

Voor een grotere oplossing kan de volledige structuur worden gebruikt.

11. Naamgevingsregels¶

Softwareoplossing¶

Gebruik een functionele en herkenbare naam.

Aanbevolen structuur:

<Functionele naam>

Of wanneer extra context nodig is:

<Klantnaam> <Functionele naam>

Goede voorbeelden:

Orderinvoer
Employee Purchase Portal
Productkoppeling
Dealerportaal
Brekz Checkout
Van Rijn Coating Orderinvoer

Vermijd

Omgeving 1
Nieuwe omgeving
Laravel omgeving
Website repository
Project klantnaam
App 2
Portal nieuw

Repository¶

Gebruik een korte technische naam in lowercase kebab-case.

Aanbevolen structuur:

<klant>-<functie>

Eventueel uitgebreid met het component:

<klant>-<functie>-<component>

Voorbeelden:

brekz-checkout
brekz-checkout-frontend
brekz-checkout-api
brekz-exact-export
van-rijn-order-portal
thystoys-mirakl-integration

Voeg geen omgevingsnaam aan de repository toe, tenzij de repository uitsluitend configuratie van die specifieke omgeving bevat.

Vermijd

brekz-production
brekz-acceptance
brekz-environment
brekz-new
brekz-v2

Deployment¶

Aanbevolen structuur:

<softwareoplossing-of-component>-<omgeving>

Voorbeelden:

brekz-checkout-production
brekz-checkout-acceptance
van-rijn-order-portal-production
thystoys-mirakl-integration-production

Domeinnamen¶

Koppel domeinnamen aan een deployment en omgeving.

Voorbeeld:

deployments:
  - name: van-rijn-order-portal-acceptance
    environment: acceptance
    url: https://acceptatie.orders.example.nl
  - name: van-rijn-order-portal-production
    environment: production
    url: https://orders.example.nl

12. Aanbevolen documentatiemodel¶

Gebruik bij voorkeur een vast gegevensmodel voor iedere softwareoplossing.

name: Orderinvoer Van Rijn Coating
type: web-application
customer: Van Rijn Coating
status: active
description: >
  Webapplicatie waarmee productieorders op tablets worden
  geregistreerd en voorzien van foto's.
components:
  - name: Order portal
    type: web-application
    repositories:
      - name: Order portal
        url: github.com/flooris/van-rijn-order-portal
    deployments:
      - name: van-rijn-order-portal-acceptance
        environment: acceptance
        url: https://acceptatie.orders.example.nl
      - name: van-rijn-order-portal-production
        environment: production
        url: https://orders.example.nl
  - name: ERP export
    type: integration
    repositories:
      - name: ERP export
        url: github.com/flooris/van-rijn-erp-export
    deployments:
      - name: van-rijn-erp-export-production
        environment: production

13. Vereenvoudigd documentatiemodel¶

Voor kleine softwareoplossingen hoeft niet iedere technische laag afzonderlijk te worden beschreven.

name: Corporate website Beumer Packaging
type: website
customer: Beumer Packaging
status: active
repository:
  url: github.com/flooris/beumer-packaging-website
environments:
  acceptance:
    url: https://acceptatie.example.nl
  production:
    url: https://www.example.nl

Gebruik alleen de complexere structuur wanneer de softwareoplossing daadwerkelijk meerdere componenten, repositories of deployments bevat.

Verhouding tot de Omgevingscode-conventie

Binnen de Flooris CRM-documentatie (docs/crm/klanten/) gebruiken we voor de environments: frontmatter een lijstvorm met prefix/url/type (zie CLAUDE.md — Omgeving Prefixes) in plaats van de geneste vorm hierboven. Deze Omgevingscode-prefixen (bv. W3W Website Prod) blijven de standaard voor automatisering en monitoring; de gegevensmodellen in dit hoofdstuk zijn aanvullende documentatietaal en geen vervanging daarvan.

14. Taalgebruik in communicatie¶

Gebruik in algemene communicatie:

Voor iedere klant beheren we één of meerdere softwareoplossingen. Een softwareoplossing kan bestaan uit meerdere applicaties, componenten, integraties en repositories en kan op meerdere omgevingen draaien.

Gebruik bij een specifieke repository:

De broncode van deze applicatie wordt beheerd in de repository brekz-checkout.

Gebruik bij een specifieke omgeving:

De nieuwe versie is beschikbaar op de acceptatieomgeving.

Gebruik bij een deployment:

De productie-deployment draait op de primaire applicatieserver.

Gebruik niet

De omgeving staat op GitHub.

Gebruik wel

De repository staat op GitHub.

Gebruik niet

We hebben een nieuwe omgeving aangemaakt voor de integratie.

Gebruik wel, afhankelijk van de situatie

We hebben een nieuwe repository aangemaakt voor de integratie.

Of:

We hebben een nieuwe acceptatieomgeving ingericht voor de integratie.

15. Instructies voor AI-agents¶

Bij het lezen, schrijven of aanpassen van documentatie moet een AI-agent de volgende regels toepassen.

Verplichte regels¶

Noem een Git-repository altijd een repository of Git-repository.
Gebruik het woord omgeving alleen voor local, development, test, acceptatie, staging of productie.
Gebruik softwareoplossing als overkoepelende term voor wat wij voor een klant ontwikkelen en beheren.
Classificeer iedere softwareoplossing waar mogelijk als: website, webportaal, webapplicatie, integratie, API of service.
Gebruik project uitsluitend voor een tijdelijk realisatie- of wijzigingstraject.
Gebruik product alleen wanneer sprake is van een herhaalbaar softwareproduct met product ownership en een roadmap.
Maak onderscheid tussen: softwareoplossing, applicatie, component, repository, deployment en omgeving.
Corrigeer bestaand taalgebruik waarin een repository ten onrechte een omgeving wordt genoemd.
Behoud bij correcties de oorspronkelijke betekenis en pas alleen de terminologie aan wanneer de context duidelijk is.
Vraag om verduidelijking wanneer uit de context niet blijkt of met "omgeving" een repository, deployment, server of echte softwareomgeving wordt bedoeld.

Interpretatieregel voor bestaande documentatie¶

Wanneer bestaande documentatie het woord omgeving gebruikt, bepaal dan uit de context wat werkelijk wordt bedoeld.

Voorbeelden:

Bestaande tekst	Waarschijnlijke betekenis
De omgeving staat op GitHub	Repository
Clone de omgeving naar je Mac	Repository
Deploy de omgeving naar productie	Applicatie, repository of release
De omgeving draait op server APP-01	Deployment
De omgeving is bereikbaar via acceptatie.example.nl	Acceptatieomgeving
Maak een nieuwe omgeving aan in Laravel Forge	Site, deployment of serverconfiguratie
De productieomgeving gebruikt database X	Productieomgeving

Pas de term alleen automatisch aan als de betekenis voldoende duidelijk is.

16. Samenvatting¶

De centrale term binnen onze organisatie is:

Softwareoplossing

Een softwareoplossing heeft een type, zoals website, webportaal, webapplicatie of integratie. Een softwareoplossing kan bestaan uit applicaties en componenten. De broncode daarvan wordt beheerd in repositories. De software wordt via deployments uitgerold naar omgevingen zoals acceptatie en productie.

Nooit vergeten

De term omgeving mag nooit als algemene naam voor een Git-repository worden gebruikt.