steid

1	# Steid
2
3	The source of truth for everything in a developer's or organization's portfolio.
4
5	## Vision
6
7	Steid is a developer/org identity and portfolio platform. It's where you host your
8	code, your writing, your projects — everything you do, in one place, under your
9	control.
10
11	Git repos are a core feature, not the whole product. Blogs, documentation, project
12	showcases, and anything else a dev or org wants to present lives here too.
13
14	Personal-first, but organizations can collaborate on it.
15
16	What makes it different from Gitea/Forgejo: those are GitHub clones scaled down.
17	Steid is portfolio-first — the profile page is the product, and repos are one kind of
18	thing that appears on it. That framing should win any tie-break.
19
20	## Core Principles
21
22	- Fast — Rust, minimal overhead
23	- Reliable — correct first, then optimize
24	- Personal-first — great for a single dev, scales to orgs
25	- Identity-centric — everything is built around who you are (user/org); auth is
26	designed in from day one, not bolted on
27
28	## Stack
29
30	Starting intent, not settled decisions. Each one gets a record in
31	[decisions/](decisions/) when it's actually made and confirmed in this build.
32
33	\| Concern \| Choice \| Decision \|
34	\|---\|---\|---\|
35	\| Web framework \| Topcoat (tokio-rs) \| — \|
36	\| Git transport \| smart HTTP via `git http-backend` \| [0001](decisions/0001-git-over-http-not-ssh.md) \|
37	\| Git auth \| personal access tokens over HTTP Basic \| [0001](decisions/0001-git-over-http-not-ssh.md) \|
38	\| Git operations \| the `git` binary, behind narrow ports \| [0006](decisions/0006-git-binary-behind-narrow-ports.md) \|
39	\| Crate layout \| single crate \| — \|
40	\| Ownership \| personal org owns repos \| — \|
41	\| URLs \| root handles, grouped routes \| [0004](decisions/0004-root-handles-grouped-routes.md) \|
42	\| Database \| SQLite via sqlx \| — \|
43
44	Architecture and conventions: [architecture.md](architecture.md).
45
46	## Milestone Ladder
47
48	A from-scratch rebuild on Topcoat. Much of this was built and verified end-to-end in a
49	previous attempt — see [progress.md](progress.md). Treat that code as reference, not as
50	a baseline.
51
52	\| # \| Milestone \| Status \|
53	\|---\|---\|---\|
54	\| 0 \| Skeleton — Topcoat app boots, config, one page, SQLite wired \| done \|
55	\| 1 \| Identity, thin — claim on first run, login, session \| done \|
56	\| 2 \| Profile page — `/{handle}` as the real profile \| done \|
57	\| 3 \| Repo model — records + bare repos on disk \| done \|
58	\| 4a \| Clone over HTTP — `git http-backend`, public repos, no auth \| done \|
59	\| 4b \| Push and tokens — PATs over HTTP Basic, push, private clone \| done \|
60	\| 5 \| Repo browsing — tree, blob, commit log \| done \|
61	\| 6 \| Writing — posts, markdown \| active \|
62	\| 7 \| Identity, full — multi-user, orgs, invites, registration policy \| not started \|
63	\| 8+ \| Projects/showcases · issues & PRs · SSH transport · federation \| not started \|
64
65	`/api` is not a milestone. It's a standing practice: every milestone that adds a use
66	case exposes it under `/api` where that makes sense. An API isn't a feature, it's a
67	second surface on work already being done — and having a third consumer keeps the use
68	case layer honest.
69
70	### Why this order
71
72	The vision calls Steid portfolio-first, but every previous ladder put portfolio behind
73	four milestones of git plumbing. Across two attempts and ~6,000 lines, Steid has
74	shipped identity, repo records, clone, push, and key auth — and not one portfolio
75	feature. Attempt #2 ended with all the git infrastructure working and nothing that
76	distinguishes it from Gitea.
77
78	The differentiator therefore shipped early: the profile page is milestone 2, not
79	milestone 6. Full multi-user identity stays deferred to 7 — personal-first means one
80	user, and there is nothing to collaborate on until there is something worth
81	collaborating on.
82
83	Git moved ahead of writing after milestone 2 shipped, deliberately reversing the
84	original order. Two reasons. The profile has a Repositories section that a visitor
85	expects to be full, and a gitforge whose repo list is permanently empty is its own kind
86	of wrong. And git-over-HTTP is the least-understood work left — everything else is CRUD
87	over SQLite, while that is pack data streamed through a subprocess — so learning what
88	Topcoat makes awkward is worth more now than after three more features are stacked on
89	top.
90
91	The risk being run knowingly: disappearing into protocol work is what ended both
92	previous attempts. Milestone 3 is deliberately small and ships something visible on the
93	profile; if milestone 4 starts to sprawl, that is the signal to bank it and go back to
94	writing.
95
96	Milestone 4 was split before it started, acting on that warning rather than waiting
97	to be surprised by it. It bundled two subsystems — personal access tokens and the smart
98	HTTP protocol — and neither shipped anything until both were done. Split, 4a is
99	anonymous clone of a public repository with no authentication code at all, which is a
100	working `git clone` in one small milestone; 4b adds tokens, push, and private clone on
101	top. If 4b sprawls, 4a has already banked the capability.
102
103	One numbering scheme. The previous attempt kept two (a roadmap ladder and a
104	separate build log with conflicting numbers) and they drifted apart within three
105	milestones. If the plan changes, edit this table — don't start a second list.
106
107	The active milestone is broken into steps in [current.md](current.md).