PitStop C4 Architecture Documentation
TODO: Work in progress. Verder controleren.
Deze pagina bevat basis C4 model diagrammen van de PitStop Garage Management System volgens de C4 model standaard van Simon Brown. Voor je eigen PitStop uitbreiding kun je deze uitbreiden. Als je tijdens uitbreiden fouten opmerkt in bestaande, graag rapporteren bij de docent.
📋 Inleiding
De PitStop applicatie is een microservices-gebaseerd garage management systeem dat demonstreert moderne software architectuur concepten zoals Microservices Architecture, CQRS (Command Query Responsibility Segregation), Event Driven Architecture etc. Zie voor verdere info de docs/wiki/code in de Pitstop repo op Github van Edwin van Wijk.
🛠️ C4 Diagrammen Tools
Deze C4 diagrammen zijn gemaakt met de C4-PlantUML library en kunnen worden gevisualiseerd op/met:
- PlantUML Online Server: http://www.plantuml.com/plantuml/uml/
- VS Code Plugin: PlantUML Extension (vereist GraphViz installatie lokaal)
📚 Referenties
- C4-PlantUML Library - Officiële C4-PlantUML repository
- VS Code PlantUML Plugin - Voor lokale ontwikkeling
- C4 Model Website - Officiële C4 model documentatie
🏗️ C4 Model Diagrammen
C4 Context Diagram
Toont het systeem in zijn context - wie gebruikt het systeem en welke externe systemen interacteren ermee.
📋 PlantUML Code - C4 Context Diagram
```plantuml
@startuml C4_Context
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
title System Context diagram for PitStop Garage Management System
Person(garage_owner, "Garage Owner", "Eigenaar van de garage die het systeem gebruikt voor dagelijkse operaties")
Person(mechanic, "Mechanic", "Monteur die werkorders beheert en voertuigen repareert")
Person(customer, "Customer", "Klant die zijn voertuig laat repareren")
Person(admin, "System Administrator", "Beheerder die het systeem onderhoudt en configureert")
System(pitstop, "PitStop Garage Management System", "Microservices-gebaseerd systeem voor garage management, inclusief klantbeheer, voertuigbeheer, werkplaats management en facturering")
System_Ext(email, "Email System", "Externe email service voor notificaties")
System_Ext(payment, "Payment Gateway", "Externe betalingsservice voor facturen")
System_Ext(parts_supplier, "Parts Supplier", "Externe leverancier van auto-onderdelen")
Rel(garage_owner, pitstop, "Manages garage operations", "HTTPS")
Rel(mechanic, pitstop, "Updates work orders and vehicle status", "HTTPS")
Rel(customer, pitstop, "Views vehicle status and receives notifications", "HTTPS")
Rel(admin, pitstop, "Configures and maintains system", "HTTPS")
Rel(pitstop, email, "Sends notifications", "SMTP")
Rel(pitstop, payment, "Processes payments", "HTTPS")
Rel(pitstop, parts_supplier, "Orders parts", "HTTPS")
@enduml
```
🎯 Systeem Context
Gebruikers
- Garage Owner: Beheert dagelijkse garage operaties
- Mechanic: Werkt met werkorders en voertuigreparaties
- Customer: Bekijkt voertuigstatus en ontvangt notificaties
- System Administrator: Onderhoudt en configureert het systeem
Externe Systemen
- Email System: Voor notificaties naar klanten en medewerkers
- Payment Gateway: Voor het verwerken van betalingen
- Parts Supplier: Voor het bestellen van auto-onderdelen
Systeem Verantwoordelijkheden
Het PitStop systeem is verantwoordelijk voor:
- Klantbeheer en registratie
- Voertuigbeheer en onderhoudshistorie
- Werkplaats planning en werkorder beheer
- Facturering en betalingen
- Notificaties en communicatie
- Audit logging en compliance
C4 Container Diagram
Toont de high-level vorm van de architectuur en hoe verantwoordelijkheden zijn verdeeld over containers.
Architectuur Toelichting
De Notification Service is een .NET Core Worker die voor lokale ontwikkeling een lokale email service gebruikt - het stuurt geen echte emails tijdens development. In productie zou deze service geïntegreerd worden met een echte SMTP provider.
De RabbitMQ Message Broker fungeert als het centrale zenuwstelsel van de architectuur, waarbij alle API's events publiceren en de worker services deze asynchroon verwerken. Dit zorgt voor loose coupling tussen services.
De Web Application fungeert als een thin client die voornamelijk API calls maakt naar de verschillende management API's. Er is geen directe database toegang vanuit de frontend.
De Audit Service is specifiek ontworpen als write-only service voor compliance doeleinden - het logt alle systeem activiteiten maar leest nooit data terug voor business logica.
📋 PlantUML Code - C4 Container Diagram
```plantuml
@startuml C4_Container
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
title Container diagram for PitStop Garage Management System
Person(garage_owner, "Garage Owner", "Eigenaar van de garage")
Person(mechanic, "Mechanic", "Monteur")
Person(customer, "Customer", "Klant")
Person(admin, "System Administrator", "Systeem beheerder")
System_Boundary(pitstop_system, "PitStop Garage Management System") {
Container(webapp, "Web Application", "ASP.NET Core", "Frontend applicatie voor garage medewerkers en klanten")
Container(customer_api, "Customer Management API", "ASP.NET Core Web API", "Beheert klantgegevens en registraties")
Container(vehicle_api, "Vehicle Management API", "ASP.NET Core Web API", "Beheert voertuiggegevens en onderhoudshistorie")
Container(workshop_api, "Workshop Management API", "ASP.NET Core Web API", "Beheert werkorders en werkplaats planning")
Container(invoice_service, "Invoice Service", ".NET Core Worker", "Genereert en beheert facturen")
Container(notification_service, "Notification Service", ".NET Core Worker", "Verstuurt notificaties via email en SMS")
Container(audit_service, "Audit Log Service", ".NET Core Worker", "Logt alle systeem activiteiten")
Container(time_service, "Time Service", ".NET Core Worker", "Beheert tijdregistratie en planning")
Container(workshop_event_handler, "Workshop Event Handler", ".NET Core Worker", "Verwerkt workshop gerelateerde events")
ContainerDb(sqlserver, "SQL Server Database", "Microsoft SQL Server", "Stores customer, vehicle, workshop and invoice data")
ContainerDb(rabbitmq, "RabbitMQ Message Broker", "RabbitMQ", "Handles asynchronous messaging between services")
}
System_Ext(email, "Email System", "SMTP")
System_Ext(payment, "Payment Gateway", "HTTPS")
System_Ext(parts_supplier, "Parts Supplier", "HTTPS")
' User interactions
Rel(garage_owner, webapp, "Uses", "HTTPS")
Rel(mechanic, webapp, "Uses", "HTTPS")
Rel(customer, webapp, "Uses", "HTTPS")
Rel(admin, webapp, "Manages", "HTTPS")
' Web app to APIs
Rel(webapp, customer_api, "Makes API calls", "HTTPS")
Rel(webapp, vehicle_api, "Makes API calls", "HTTPS")
Rel(webapp, workshop_api, "Makes API calls", "HTTPS")
' APIs to database
Rel(customer_api, sqlserver, "Reads from and writes to", "SQL/TCP")
Rel(vehicle_api, sqlserver, "Reads from and writes to", "SQL/TCP")
Rel(workshop_api, sqlserver, "Reads from and writes to", "SQL/TCP")
' Event-driven communication
Rel(customer_api, rabbitmq, "Publishes events", "AMQP")
Rel(vehicle_api, rabbitmq, "Publishes events", "AMQP")
Rel(workshop_api, rabbitmq, "Publishes events", "AMQP")
Rel(rabbitmq, invoice_service, "Delivers events", "AMQP")
Rel(rabbitmq, notification_service, "Delivers events", "AMQP")
Rel(rabbitmq, audit_service, "Delivers events", "AMQP")
Rel(rabbitmq, time_service, "Delivers events", "AMQP")
Rel(rabbitmq, workshop_event_handler, "Delivers events", "AMQP")
' Services to database
Rel(invoice_service, sqlserver, "Reads from and writes to", "SQL/TCP")
Rel(notification_service, sqlserver, "Reads from and writes to", "SQL/TCP")
Rel(audit_service, sqlserver, "Writes to", "SQL/TCP")
Rel(time_service, sqlserver, "Reads from and writes to", "SQL/TCP")
Rel(workshop_event_handler, sqlserver, "Reads from and writes to", "SQL/TCP")
' External integrations
Rel(invoice_service, payment, "Processes payments", "HTTPS")
Rel(notification_service, email, "Sends notifications", "SMTP")
Rel(workshop_api, parts_supplier, "Orders parts", "HTTPS")
@enduml
```