Skip to content

Commit 2f0a2fa

Browse files
tgiachitgiachi
authored
Merge pull request #36 from tgiachi/docs/visual
docs: landing redesign and architecture diagrams
2 parents 94bb9dc + 83965d0 commit 2f0a2fa

7 files changed

Lines changed: 165 additions & 16 deletions

File tree

‎docs/articles/concepts/architecture.md‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,20 @@ Higher layers depend on lower ones, never the reverse.
2121

2222
```mermaid
2323
graph TD
24-
Core[SquidStd.Core] --> Services[SquidStd.Services.Core]
25-
Abstr[*.Abstractions contracts] --> Providers[Provider packages]
26-
Services --> Host[SquidStdBootstrap host]
24+
subgraph Foundation
25+
Core[SquidStd.Core<br/>primitives, options]
26+
Abstr[SquidStd.*.Abstractions<br/>contracts + DTOs]
27+
end
28+
subgraph Implementations
29+
Services[SquidStd.Services.Core<br/>config, events, jobs, timers]
30+
Providers[Provider packages<br/>Redis, RabbitMQ, S3, ...]
31+
InMem[In-memory providers<br/>for tests]
32+
end
33+
Core --> Services
34+
Core --> Abstr
35+
Abstr --> Providers
36+
Abstr --> InMem
37+
Services --> Host[SquidStdBootstrap]
2738
Providers --> Host
2839
Host --> App[Your application]
2940
```

‎docs/articles/messaging.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,16 @@
11
[!include[](../../src/SquidStd.Messaging/README.md)]
2+
3+
## How messages flow
4+
5+
```mermaid
6+
flowchart LR
7+
P[Publisher] -->|enqueue| Q[(Queue)]
8+
Q -->|competing consumers,<br/>one receives| C1[Consumer A]
9+
Q -.-> C2[Consumer B]
10+
11+
P2[Publisher] -->|publish| T((Topic))
12+
T -->|fan-out,<br/>all receive| S1[Subscriber A]
13+
T --> S2[Subscriber B]
14+
```
15+
16+
Queues deliver each message to exactly one consumer (work distribution); topics fan out every message to all subscribers (notifications). Both are behind `IMessageQueue` / `IMessageTopic` regardless of the backend.

‎docs/articles/network.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,14 @@
11
[!include[](../../src/SquidStd.Network/README.md)]
2+
3+
## The receive pipeline
4+
5+
```mermaid
6+
flowchart LR
7+
Bytes[Raw bytes] --> MW1[Middleware 1]
8+
MW1 --> MW2[Middleware N]
9+
MW2 --> Framing[INetFramer<br/>frame extraction]
10+
Framing --> Handler[Message handler]
11+
Handler -->|response| Out[Write pipeline]
12+
```
13+
14+
Each connection runs inbound bytes through the middleware chain (`INetMiddleware`), then the configured `INetFramer` splits the accumulated stream into discrete frames before they reach your handler. The write path runs the same middleware chain on outgoing payloads before the bytes hit the socket.

‎docs/articles/scheduler.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,19 @@ eventLoop:
6464
SlowTickThresholdMs: 250 # warn above this per-tick time
6565
```
6666
67+
```mermaid
68+
flowchart TD
69+
subgraph Drivers["Drivers - register exactly one"]
70+
EL[EventLoopService<br/>frame-rate thread]
71+
PU[TimerWheelPumpService<br/>periodic pump]
72+
end
73+
EL -->|UpdateTicksDelta| W[Timer wheel]
74+
PU -->|UpdateTicksDelta| W
75+
EL -->|DrainPending| D[MainThreadDispatcher]
76+
W --> T1[Cron jobs]
77+
W --> T2[Wheel timers]
78+
```
79+
6780
### Event loop vs. timer-wheel pump
6881

6982
Both `EventLoopService` and `TimerWheelPumpService` advance the timer wheel, so they are **mutually

‎docs/articles/vfs.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,14 @@
11
[!include[](../../src/SquidStd.Vfs/README.md)]
2+
3+
## Decorator composition
4+
5+
```mermaid
6+
flowchart LR
7+
App[Your code] --> RO[ReadOnly]
8+
RO --> CH[Chroot /prefix]
9+
CH --> OV[Overlay]
10+
OV --> Base[(Base backend<br/>physical / zip / S3 / database)]
11+
OV -.->|writes| Upper[(Overlay backend)]
12+
```
13+
14+
Decorators wrap any `IVirtualFileSystem`: read-only guards, chroot prefixes, and overlays compose freely over the physical, zip, S3 or database backends.

‎docs/index.md‎

Lines changed: 45 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,25 +2,57 @@
22
_layout: landing
33
---
44

5-
<p align="center">
6-
<img src="images/logo.png" alt="SquidStd" width="140" height="140" />
7-
</p>
5+
<div class="sqd-hero">
6+
<img src="images/logo.png" alt="SquidStd" width="120" height="120" />
7+
<h1>SquidStd</h1>
8+
<p class="sqd-tagline">A batteries-included, modular standard library for .NET 10 - distilled from years
9+
of building real-world server software. Each capability ships behind a small contract with an in-memory
10+
implementation for tests and a production backend.</p>
11+
<p class="sqd-badges">
12+
<a href="https://www.nuget.org/packages/SquidStd.Core"><img src="https://img.shields.io/nuget/v/SquidStd.Core?label=nuget&color=1390A3" alt="NuGet" /></a>
13+
<a href="https://github.com/tgiachi/squid-std/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/tgiachi/squid-std/ci.yml?branch=main&label=CI" alt="CI" /></a>
14+
<a href="https://github.com/tgiachi/squid-std/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-4BB4BD" alt="MIT" /></a>
15+
</p>
16+
<pre class="sqd-install"><code>dotnet add package SquidStd.Services.Core</code></pre>
17+
<p class="sqd-cta">
18+
<a class="btn btn-primary" href="tutorials/getting-started.md">Get started</a>
19+
<a class="btn btn-outline-primary" href="api/index.md">API reference</a>
20+
</p>
21+
</div>
822

9-
# SquidStd
23+
## Capabilities
1024

11-
A batteries-included, modular standard library for .NET 10 - distilled from years of building
12-
real-world server software. Each capability ships behind a small contract with an in-memory
13-
implementation for tests and a production backend, published as a focused NuGet package.
25+
<div class="sqd-cards">
26+
<a class="sqd-card" href="articles/messaging-abstractions.md"><b>Messaging</b><span>Queues &amp; pub/sub - in-memory, RabbitMQ, SQS</span></a>
27+
<a class="sqd-card" href="articles/caching-abstractions.md"><b>Caching</b><span>In-memory or Redis behind one contract</span></a>
28+
<a class="sqd-card" href="articles/storage-abstractions.md"><b>Storage</b><span>Files &amp; objects - local or S3/MinIO</span></a>
29+
<a class="sqd-card" href="articles/vfs-abstractions.md"><b>Virtual FS</b><span>Composable filesystems with decorators</span></a>
30+
<a class="sqd-card" href="articles/database-abstractions.md"><b>Database</b><span>FreeSql data access with migrations</span></a>
31+
<a class="sqd-card" href="articles/crypto.md"><b>Crypto</b><span>PGP, password ciphers, encrypted vaults</span></a>
32+
<a class="sqd-card" href="articles/mail-abstractions.md"><b>Mail</b><span>Send, receive and queue email</span></a>
33+
<a class="sqd-card" href="articles/workers-abstractions.md"><b>Workers</b><span>Job handlers, heartbeats, a manager API</span></a>
34+
<a class="sqd-card" href="articles/actors.md"><b>Actors</b><span>Mailbox-based concurrency primitives</span></a>
35+
<a class="sqd-card" href="articles/network.md"><b>Network</b><span>TCP/UDP servers with framing pipelines</span></a>
36+
<a class="sqd-card" href="articles/templating.md"><b>Templating</b><span>Scriban templates with includes</span></a>
37+
<a class="sqd-card" href="articles/telemetry-abstractions.md"><b>Telemetry</b><span>OpenTelemetry tracing &amp; metrics</span></a>
38+
</div>
1439

15-
Security & crypto, configuration, persistence, messaging, caching, storage, a virtual filesystem,
16-
search, mail, workers, actors, telemetry, scripting - take only what you need.
40+
## Quick start
1741

18-
## Start here
42+
```csharp
43+
var container = new Container();
44+
container.AddInMemoryMessaging();
1945

20-
- **[Tutorials](tutorials/index.md)** - learn by building: bootstrap, caching, messaging, workers,
21-
crypto, persistence, and more.
46+
var bootstrap = SquidStdBootstrap.Create(new SquidStdOptions { ConfigName = "myapp" }, container);
47+
await bootstrap.StartAsync();
48+
```
49+
50+
Continue with the [getting started tutorial](tutorials/getting-started.md).
51+
52+
## Explore
53+
54+
- **[Tutorials](tutorials/index.md)** - learn by building: bootstrap, caching, messaging, workers, crypto, persistence, and more.
2255
- **[Guides](articles/guides/configuration.md)** - task-focused how-to and "which provider" decision guides.
2356
- **[Concepts](articles/concepts/architecture.md)** - the architecture and the ideas behind it.
2457
- **[Packages](articles/getting-started.md)** - per-package reference.
25-
- **[API reference](api/index.md)** - full type/member documentation.
2658
- **[Felix Network](articles/felix.md)** - companion secure binary mesh-networking library (.NET + C/ESP32).

‎docs/templates/squidstd/public/main.css‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,3 +57,55 @@ table > thead { background-color: rgba(75, 180, 189, 0.12); }
5757
article h1[align] {
5858
text-align: start;
5959
}
60+
61+
/* ---- Landing page ---- */
62+
.sqd-hero {
63+
text-align: center;
64+
padding: 3rem 1rem 2.5rem;
65+
margin: -1rem -1rem 2rem;
66+
background: linear-gradient(160deg, var(--sqd-brand-dark), var(--sqd-brand-deep));
67+
color: #eaf6f8;
68+
border-radius: 0 0 1rem 1rem;
69+
}
70+
.sqd-hero h1 { color: #fff; margin-top: 0.75rem; }
71+
.sqd-tagline { max-width: 46rem; margin: 0.75rem auto 1rem; opacity: 0.92; }
72+
.sqd-badges img { margin: 0 0.15rem; }
73+
.sqd-install {
74+
display: inline-block;
75+
background: var(--sqd-ink);
76+
border-radius: 0.5rem;
77+
padding: 0.6rem 1.4rem;
78+
margin: 0.75rem 0;
79+
}
80+
.sqd-install code { color: var(--sqd-accent); background: transparent; }
81+
.sqd-cta { margin-top: 0.5rem; }
82+
.sqd-cta .btn { margin: 0 0.25rem; }
83+
84+
.sqd-cards {
85+
display: grid;
86+
grid-template-columns: repeat(auto-fill, minmax(14rem, 1fr));
87+
gap: 0.9rem;
88+
margin: 1.25rem 0 2rem;
89+
}
90+
.sqd-card {
91+
display: flex;
92+
flex-direction: column;
93+
gap: 0.25rem;
94+
padding: 0.9rem 1rem;
95+
border: 1px solid rgba(19, 144, 163, 0.25);
96+
border-radius: 0.6rem;
97+
text-decoration: none;
98+
color: inherit;
99+
transition: border-color 0.15s, transform 0.15s;
100+
}
101+
.sqd-card:hover {
102+
border-color: var(--sqd-brand);
103+
transform: translateY(-2px);
104+
text-decoration: none;
105+
}
106+
.sqd-card b { color: var(--sqd-brand-deep); }
107+
.sqd-card span { font-size: 0.85rem; opacity: 0.8; }
108+
109+
[data-bs-theme="dark"] .sqd-card b { color: var(--sqd-accent); }
110+
[data-bs-theme="dark"] .sqd-card { border-color: rgba(75, 180, 189, 0.25); }
111+
[data-bs-theme="dark"] .sqd-card:hover { border-color: var(--sqd-accent); }

0 commit comments

Comments
 (0)