Skip to content

Commit 7398fc1

Browse files
eboodyeboody
committed
Tighten root README copy
1 parent dfe157f commit 7398fc1

1 file changed

Lines changed: 76 additions & 41 deletions

File tree

‎README.md‎

Lines changed: 76 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<source media="(prefers-color-scheme: dark)" srcset="./crates/http/static/eran.codes-dark.svg">
44
<img alt="eran.codes logo" src="./crates/http/static/eran.codes-light.svg" width="280">
55
</picture>
6-
<p><strong>A Rust portfolio application built to demonstrate architecture, realtime delivery, and operational clarity under load.</strong></p>
6+
<p><strong>A Rust portfolio application focused on architecture, realtime delivery, and runtime visibility.</strong></p>
77
<p>
88
<a href="https://eran.codes">Live site</a>
99
·
@@ -18,44 +18,23 @@
1818

1919
# eran.codes
2020

21-
`eran_codes` is the codebase behind my portfolio site. It is designed to show how I build software when boundaries, runtime behavior, and maintainability matter more than shipping another generic web app.
21+
`eran_codes` is the Rust workspace behind my portfolio site at <https://eran.codes>.
2222

23-
The demos are not decoration. They are the architecture made inspectable.
23+
This project is a working portfolio site and a place to show how I structure Rust web systems with clear boundaries, realtime updates, and visible runtime behavior.
2424

25-
![Runtime architecture overview](./docs/static/readme/runtime-architecture.svg)
25+
The focus is on system behavior rather than isolated features: crate boundaries, SSE-driven UI state, request tracing, and the operational surfaces around them.
2626

27-
## What This Repo Is Designed To Prove
27+
![Runtime architecture overview](./docs/static/readme/runtime-architecture.svg)
2828

29-
- **Boundary discipline.** `http`, `app`, `domain`, and `infra` are separate crates with distinct responsibilities, not one module tree with polite comments.
30-
- **Realtime delivery without hand-waving.** UI state converges through SSE + Datastar, with session-aware stream routing instead of ad hoc polling.
31-
- **Observability as a product feature.** Request metadata, backend flow, and live operational timelines are visible in the UI, not buried in logs alone.
32-
- **Operational thinking.** Sessions are durable, tracing is layered, and the request-burst surface stresses the app without abandoning clarity.
33-
- **Typed view and domain contracts.** Maud components, newtypes, enums, and workflow surfaces replace template sprawl and brittle stringly logic.
29+
## What This System Demonstrates
3430

35-
## Evaluate It In Five Minutes
31+
- **Boundary discipline.** `http`, `app`, `domain`, and `infra` are separate crates with clear responsibilities.
32+
- **Realtime delivery.** UI state converges through SSE + Datastar with session-aware stream routing.
33+
- **Runtime visibility.** Request metadata, backend flow, and live operational timelines are surfaced in the UI.
34+
- **Operational concerns in the app itself.** Sessions are durable, tracing is layered, and the request-burst surface is there to inspect runtime behavior.
35+
- **Typed contracts across the stack.** Maud components, domain newtypes and enums, and explicit workflow types keep rendering and business logic structured.
3636

37-
1. Visit [`/lab`](https://eran.codes/lab).
38-
This is the fastest proof surface. It combines live chat, request burst traffic, auth/session panels, and the operational timeline.
39-
40-
2. Visit the focused work pages.
41-
- [`/work/chat-realtime`](https://eran.codes/work/chat-realtime)
42-
- [`/work/command-sse`](https://eran.codes/work/command-sse)
43-
- [`/work/operational-visibility`](https://eran.codes/work/operational-visibility)
44-
45-
3. Read the engineering rationale.
46-
- [Docs hub](./docs/README.md)
47-
- [Professionalism In Practice](./docs/professionalism-breakdown.md)
48-
- [Portfolio Demo Concepts](./docs/portfolio-demos.md)
49-
- [Auth + Sessions](./docs/auth-sessions.md)
50-
- [Tracing Plan](./docs/tracing.md)
51-
52-
4. Inspect the crate boundaries.
53-
- [domain](./crates/domain/README.md)
54-
- [app](./crates/app/README.md)
55-
- [infra](./crates/infra/README.md)
56-
- [http](./crates/http/README.md)
57-
58-
## Architecture At A Glance
37+
## Architecture Overview
5938

6039
```text
6140
browser
@@ -73,18 +52,74 @@ trace pipeline
7352
-> deeper diagnostic stream for engineering visibility
7453
```
7554

76-
`[src/main.rs](./src/main.rs)` is the composition root. It wires tracing, Postgres-backed sessions, app services, the SSE registry, and the HTTP router into one runtime.
55+
At the crate-boundary level, the workspace stays intentionally layered:
56+
57+
```text
58+
browser
59+
|
60+
v
61+
http
62+
routing, handlers, SSE, Maud
63+
|
64+
v
65+
app
66+
use-case services
67+
|
68+
v
69+
domain
70+
types and invariants
71+
72+
infra supplies the Postgres, hashing, repository,
73+
and session-backed runtime pieces used by the outer layers.
74+
```
75+
76+
`[src/main.rs](./src/main.rs)` is the composition root. It wires:
7777

78-
## Core Runtime Surfaces
78+
- tracing
79+
- Postgres-backed sessions
80+
- app services
81+
- the SSE registry
82+
- the HTTP router
7983

80-
| Surface | Path | What it demonstrates |
84+
into one runtime.
85+
86+
## Observe The System Running
87+
88+
These pages expose runtime behavior directly in the UI.
89+
90+
| Surface | Path | What to observe |
8191
| --- | --- | --- |
8292
| Lab | [`/lab`](https://eran.codes/lab) | Live chat, request burst traffic, auth/session panels, and the operational timeline |
8393
| Chat system | [`/work/chat-realtime`](https://eran.codes/work/chat-realtime) | Persisted messaging, moderation, rate limiting, and SSE fanout |
8494
| Command + SSE | [`/work/command-sse`](https://eran.codes/work/command-sse) | Datastar command flow, server-authoritative state, and SSE convergence |
8595
| Operational visibility | [`/work/operational-visibility`](https://eran.codes/work/operational-visibility) | Request tracing, backend flow grouping, and UI-visible runtime behavior |
8696
| Auth durability | [`/register`](https://eran.codes/register) -> [`/login`](https://eran.codes/login) -> [`/protected`](https://eran.codes/protected) | Session lifecycle, auth enforcement, and secure persistent sessions |
8797

98+
While interacting, watch the operational timeline panel. It shows requests, commands, and state changes as they happen.
99+
100+
## Evaluate It In Five Minutes
101+
102+
1. Visit [`/lab`](https://eran.codes/lab).
103+
This is the quickest way to see the main pieces together: live chat, request burst traffic, auth/session panels, and the operational timeline.
104+
105+
2. Visit the focused work pages.
106+
- [`/work/chat-realtime`](https://eran.codes/work/chat-realtime)
107+
- [`/work/command-sse`](https://eran.codes/work/command-sse)
108+
- [`/work/operational-visibility`](https://eran.codes/work/operational-visibility)
109+
110+
3. Read the engineering rationale.
111+
- [Docs hub](./docs/README.md)
112+
- [Professionalism In Practice](./docs/professionalism-breakdown.md)
113+
- [Portfolio Demo Concepts](./docs/portfolio-demos.md)
114+
- [Auth + Sessions](./docs/auth-sessions.md)
115+
- [Tracing Plan](./docs/tracing.md)
116+
117+
4. Inspect the crate boundaries.
118+
- [domain](./crates/domain/README.md)
119+
- [app](./crates/app/README.md)
120+
- [infra](./crates/infra/README.md)
121+
- [http](./crates/http/README.md)
122+
88123
## Run It Locally
89124

90125
Required environment:
@@ -108,14 +143,14 @@ cargo run
108143

109144
Then open `http://127.0.0.1:3000/` or `http://127.0.0.1:3000/lab`.
110145

111-
## Codebase Guide
146+
## Codebase Map
112147

113148
| Area | Role | Start here |
114149
| --- | --- | --- |
115150
| [domain](./crates/domain/README.md) | Pure business types and invariants | `user` and `chat` modules |
116151
| [app](./crates/app/README.md) | Use cases, policy, and external contracts | auth and chat services |
117152
| [infra](./crates/infra/README.md) | Postgres, hashing, repositories, and migrations | auth repo, chat repo, config |
118-
| [http](./crates/http/README.md) | Router, handlers, SSE, Maud views, trace surfaces | router, handlers, views, `trace_log` |
153+
| [http](./crates/http/README.md) | Router, handlers, SSE, Maud views, component surfaces, and trace surfaces | router, handlers, views, `trace_log` |
119154
| [utils](./crates/utils/README.md) | Small shared helpers and developer tooling | `visual_snapshot` and support utilities |
120155

121156
## Read The System Like This
@@ -139,13 +174,13 @@ Then open `http://127.0.0.1:3000/` or `http://127.0.0.1:3000/lab`.
139174
- [Handlers](./crates/http/src/handlers/README.md)
140175
- [Views](./crates/http/src/views/README.md)
141176

142-
## Design Bias
177+
## Design Principles
143178

144-
This repo intentionally optimizes for:
179+
This repo favors:
145180
- explicit boundaries over convenience coupling
146181
- typed invariants over stringly state
147182
- visible runtime behavior over hidden magic
148183
- reusable render components over template duplication
149184
- clear composition roots over implicit wiring
150185

151-
That bias is the point of the project.
186+
Those tradeoffs are consistent across the codebase.

0 commit comments

Comments
 (0)