Skip to content

Commit 0083a11

Browse files
author
vp
committed
feat(docs): enhance documentation with new architecture, decisions, and examples sections
1 parent 4369024 commit 0083a11

12 files changed

Lines changed: 596 additions & 7 deletions

‎README.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,6 @@ The best entry point into the current documentation set is the
148148
- [GettingStarted (Basic)](https://github.com/bridgingIT/bITdevKit.Examples.GettingStarted)
149149
- [BookFiesta (DDD)](https://github.com/BridgingIT-GmbH/bITdevKit.Examples.BookFiesta)
150150
- [EventStore (CQRS)](https://github.com/bridgingit/bitdevkit/examples)
151-
- [DinnerFiesta](https://github.com/bridgingit/bitdevkit/examples)
152151
- [WeatherForecast](https://github.com/bridgingit/bitdevkit/examples)
153152

154153
## Performance Benchmarks

‎docs/site/architecture.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: Architecture
3+
---
4+
5+
# Architecture
6+
7+
`bITdevKit` is designed around clean architecture with modular vertical slices. The goal is to keep
8+
business logic explicit, testable, and isolated from infrastructure choices.
9+
10+
## High-level architecture map
11+
12+
```mermaid
13+
flowchart TB
14+
Presentation[Presentation]
15+
Infrastructure[Infrastructure]
16+
Application[Application]
17+
Domain[Domain]
18+
19+
Presentation --> Application
20+
Infrastructure --> Application
21+
Infrastructure --> Domain
22+
Application --> Domain
23+
```
24+
25+
## Layer responsibilities
26+
27+
### Domain
28+
29+
- aggregates, entities, value objects, typed ids
30+
- domain events, domain policies, and business rules
31+
- no dependency on outer layers
32+
33+
### Application
34+
35+
- commands, queries, handlers, DTOs, specifications
36+
- orchestration through requester/notifier flows
37+
- depends on domain, not on infrastructure
38+
39+
### Infrastructure
40+
41+
- persistence, messaging transports, queue brokers, storage providers
42+
- implements abstractions required by inner layers
43+
- contains integration details and operational mechanics
44+
45+
### Presentation
46+
47+
- minimal API endpoints, web-facing modules, console-facing features
48+
- request/response mapping and endpoint composition
49+
50+
## Modular vertical slices
51+
52+
The preferred shape is a modular monolith where each module owns its own domain, application,
53+
infrastructure, and presentation concerns.
54+
55+
```text
56+
Module/
57+
├── Module.Domain
58+
├── Module.Application
59+
├── Module.Infrastructure
60+
└── Module.Presentation
61+
```
62+
63+
This keeps business capabilities cohesive while still allowing a single host application to compose
64+
many modules together.
65+
66+
## Request flow in practice
67+
68+
```mermaid
69+
sequenceDiagram
70+
participant Client
71+
participant Endpoint as Presentation Endpoint
72+
participant Requester as IRequester
73+
participant Handler as Application Handler
74+
participant Domain as Aggregate
75+
participant Repository as Repository / Provider
76+
77+
Client->>Endpoint: HTTP request
78+
Endpoint->>Requester: SendAsync(command/query)
79+
Requester->>Handler: Dispatch through behaviors
80+
Handler->>Domain: Execute business logic
81+
Handler->>Repository: Persist or query
82+
Repository-->>Handler: Result
83+
Handler-->>Requester: Result
84+
Requester-->>Endpoint: Result
85+
Endpoint-->>Client: HTTP response
86+
```
87+
88+
## Architectural building blocks that matter most
89+
90+
- [DDD Introduction](reference/introduction-ddd-guide.md)
91+
- [Domain](reference/features-domain.md)
92+
- [Application Commands and Queries](reference/features-application-commands-queries.md)
93+
- [Requester and Notifier](reference/features-requester-notifier.md)
94+
- [Modules](reference/features-modules.md)
95+
- [Presentation Endpoints](reference/features-presentation-endpoints.md)
96+
97+
## Related decisions
98+
99+
- [Messaging vs Queueing](decisions-messaging-vs-queueing.md)
100+
- [Repository vs ActiveEntity](decisions-repository-vs-activeentity.md)

‎docs/site/assets/stylesheets/extra.css‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,10 @@ pre,
180180
margin-top: 1.4rem;
181181
}
182182

183+
.section-linkout {
184+
margin: -0.35rem 0 1rem;
185+
}
186+
183187
.cta-button,
184188
.capability-card,
185189
.gateway-card,
@@ -431,6 +435,19 @@ pre,
431435
text-decoration: none !important;
432436
}
433437

438+
.snippet-panel {
439+
margin: 1rem 0 1.4rem;
440+
padding: 1rem;
441+
border-radius: var(--bdk-radius-sm);
442+
border: 1px solid var(--bdk-border);
443+
background: var(--bdk-card-bg);
444+
}
445+
446+
.snippet-panel .highlight,
447+
.snippet-panel pre {
448+
margin: 0;
449+
}
450+
434451
.closing-panel {
435452
grid-template-columns: 1fr;
436453
}

‎docs/site/decisions-messaging-vs-queueing.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: Messaging vs Queueing
3+
---
4+
5+
# Messaging vs Queueing
6+
7+
`Messaging` and `Queueing` are related, but they solve different problems.
8+
9+
## Choose Messaging when
10+
11+
- one event should fan out to multiple handlers
12+
- producers should not care which consumers react
13+
- the model is event-driven and publish/subscribe oriented
14+
- integration or side effects should be loosely coupled
15+
16+
See:
17+
[Messaging](reference/features-messaging.md)
18+
19+
## Choose Queueing when
20+
21+
- one work item should be handled by one logical consumer
22+
- retries, waiting-for-handler behavior, or durable work dispatch matter
23+
- background work needs operational visibility
24+
- the model is work ownership, not event fan-out
25+
26+
See:
27+
[Queueing](reference/features-queueing.md)
28+
29+
## Quick comparison
30+
31+
| Concern | Messaging | Queueing |
32+
|---|---|---|
33+
| Delivery style | Publish/subscribe | Single-consumer work dispatch |
34+
| Typical fan-out | One-to-many | One-to-one |
35+
| Best for | Events and reactions | Background work items |
36+
| Consumer model | Multiple handlers may react | One handler owns one message type |
37+
| Operational focus | Event propagation | Work processing and queue control |
38+
39+
## Practical rule of thumb
40+
41+
Use `Messaging` when something happened.
42+
43+
Use `Queueing` when something needs to be processed.

‎docs/site/decisions-repository-vs-activeentity.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: Repository vs ActiveEntity
3+
---
4+
5+
# Repository vs ActiveEntity
6+
7+
`bITdevKit` supports both patterns. The right choice depends on the complexity of the domain and the
8+
kind of codebase being built.
9+
10+
## Choose Repository when
11+
12+
- aggregates and domain boundaries matter
13+
- query specifications or richer composition are needed
14+
- strict separation of concerns is important
15+
- the codebase is expected to grow in complexity
16+
17+
See:
18+
[Domain Repositories](reference/features-domain-repositories.md)
19+
20+
## Choose ActiveEntity when
21+
22+
- the scenario is more CRUD-oriented
23+
- development speed matters more than abstraction purity
24+
- the domain is simple and the persistence model is straightforward
25+
- a more direct style is acceptable
26+
27+
See:
28+
[ActiveEntity](reference/features-domain-activeentity.md)
29+
30+
## Quick comparison
31+
32+
| Concern | Repository | ActiveEntity |
33+
|---|---|---|
34+
| Complexity fit | Better for richer domains | Better for simpler CRUD-style domains |
35+
| Testing | Clear abstractions for mocking or substitution | More direct persistence style |
36+
| DDD alignment | Stronger aggregate boundary emphasis | Lighter-weight model |
37+
| Query flexibility | Better for specifications and filtering | More limited |
38+
| Onboarding simplicity | More concepts up front | Easier to start with |
39+
40+
## Practical rule of thumb
41+
42+
Start with `Repository` when the domain model is expected to matter.
43+
44+
Use `ActiveEntity` when speed and simplicity are the higher priority.

‎docs/site/decisions.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Decisions
3+
---
4+
5+
# Decisions
6+
7+
These short guides help with the practical tradeoffs that developers usually hit early when working
8+
with `bITdevKit`.
9+
10+
## Available guides
11+
12+
- [Messaging vs Queueing](decisions-messaging-vs-queueing.md)
13+
- [Repository vs ActiveEntity](decisions-repository-vs-activeentity.md)
14+
15+
## Why these pages exist
16+
17+
The documentation describes the features individually. These guides explain when to choose one
18+
approach over another in a real application.

‎docs/site/examples.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: Examples
3+
---
4+
5+
# Examples
6+
7+
The examples are the best way to see how the building blocks come together in real code.
8+
9+
## Primary onboarding example
10+
11+
### GettingStarted
12+
13+
Repository:
14+
[bITdevKit.Examples.GettingStarted](https://github.com/BridgingIT-GmbH/bITdevKit.Examples.GettingStarted)
15+
16+
Best for:
17+
18+
- first contact with the devkit
19+
- understanding the intended project shape
20+
- following the concepts from docs into a focused runnable example
21+
22+
## Repository examples
23+
24+
### DoFiesta
25+
26+
Path:
27+
[`examples/DoFiesta`](https://github.com/bridgingIT/bITdevKit/tree/main/examples/DoFiesta)
28+
29+
Best for:
30+
31+
- broader application composition
32+
- operational and integration-oriented scenarios
33+
- seeing more of the surrounding infrastructure in context
34+
35+
### EventSourcingDemo
36+
37+
Path:
38+
[`examples/EventSourcingDemo`](https://github.com/bridgingIT/bITdevKit/tree/main/examples/EventSourcingDemo)
39+
40+
Best for:
41+
42+
- event-sourcing-oriented exploration
43+
- understanding how event-driven persistence concepts fit into the devkit
44+
45+
### WeatherForecast
46+
47+
Path:
48+
[`examples/WeatherForecast`](https://github.com/bridgingIT/bITdevKit/tree/main/examples/WeatherForecast)
49+
50+
Best for:
51+
52+
- a lighter-weight example
53+
- fast experimentation with less surface area
54+
55+
## Suggested progression
56+
57+
1. Start with [Getting Started](getting-started.md)
58+
2. Run the `GettingStarted` example
59+
3. Read the [DDD Introduction](reference/introduction-ddd-guide.md)
60+
4. Move to `DoFiesta` or `EventSourcingDemo` depending on the scenario of interest

‎docs/site/getting-started.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,10 @@ docs for `Domain`, `Results`, `Requester and Notifier`, `Modules`, and `Presenta
6767

6868
## What to read next
6969

70+
- Read [Why bITdevKit](why.md) for the positioning and fit of the devkit.
71+
- Read [Architecture](architecture.md) for the layer map, module shape, and request flow.
72+
- Read [Examples](examples.md) for the recommended progression through the sample applications.
73+
- Read [Packages](packages.md) to understand the repository as grouped package families.
7074
- Use the [Overview](reference/index.md) when you want the complete list of public framework topics.
7175
- Use the [Templates](templates.md) page when you want to scaffold your own solution or add modules.
7276
- Move into the example applications once you want to see how the pieces fit together in code.

0 commit comments

Comments
 (0)