Revise README.md for clarity and structure: Updated tech stack details, improved setup instructions, and enhanced type safety explanations. Added architecture diagrams and refined common commands for better user guidance.

Rykuno · Rykuno · commit b21a7a247b03 · 2026-02-19T22:13:45.000-06:00
diff --git a/README.md b/README.md
@@ -1,123 +1,197 @@
 # SojuStack
 
-My constantly updated opinionated stack for constructing new Fullstack(Web/Mobile/Backend) applications.
+Opinionated, production-minded full-stack starter with strong TypeScript ergonomics and end-to-end type safety.
 
-## Getting Started
+## Tech Stack
 
-I've provided both automated and manual setup options to fit your workflow.
+### Monorepo and Tooling
 
-### 🚀 Quick Start (Automated)
+- `pnpm` workspaces
+- `turbo` task orchestration
+- `TypeScript` everywhere
+- `oxlint` + `oxfmt`
+- `lefthook` (pre-push checks)
 
-Only use quick-start for trying the stack out initially. Don't use this during actual development.
+### Web (`apps/web`)
 
-```sh
-$ pnpm dev:setup
+- `TanStack Start` + `TanStack Router`
+- `TanStack Query`
+- `openapi-fetch` generated client types
+- `Tailwind CSS` + `shadcn` + `@base-ui/react`
+- `better-auth` client integration
+
+### API (`apps/api`)
+
+- `NestJS` (v11)
+- `Drizzle ORM` + `drizzle-kit`
+- `PostgreSQL`
+- `Valkey`/Redis-compatible caching via `Keyv`
+- `Better Auth`
+- OpenAPI generation (`@nestjs/swagger` + `openapi-typescript`)
+
+### Local Infra (`docker-compose.yaml`)
+
+- `Postgres`
+- `Valkey`
+- `Mailpit`
+- `RustFS` (S3-compatible object storage)
+
+## Architecture
+
+```mermaid
+flowchart LR
+  U[User] --> W[Web App<br/>TanStack Start]
+  W -->|HTTP + Cookies| A[API<br/>NestJS]
+  A --> P[(PostgreSQL)]
+  A --> V[(Valkey)]
+  A --> S[(RustFS / S3-compatible)]
+  A --> M[Mailpit]
 ```
 
-### 🛠️ Manual Setup (Recommended)
+## Type-Safe Flow
 
-For more control over the setup process, run the following in the order listed at the root of the project.
+```mermaid
+sequenceDiagram
+  participant FE as Web
+  participant API as NestJS API
+  participant OAS as OpenAPI Types
 
-```sh
-# 1. Create environment files
-$ cp apps/api/.env.example apps/api/.env
-$ cp apps/web/.env.example apps/web/.env
+  FE->>API: Request typed by openapi-fetch client
+  API-->>FE: Response typed by generated schema
+  API->>OAS: Generate/update openapi.d.ts
+  OAS-->>FE: Compile-time contract updates
+```
 
-# 2. Install dependencies
-$ pnpm install
+## Getting Started
 
-# 3. Start Docker services
-$ docker-compose up -d
+### Quick Trial (Automated)
 
-# 4. Setup database
-$ pnpm -C ./apps/api db:push
+Use this only for first-time trial runs:
 
-# 5. Start development servers
-$ pnpm dev
+```sh
+pnpm dev:setup
 ```
 
-#### Default Service URLs
+### Manual Setup (Recommended)
+
+```sh
+# 1) Create env files
+cp apps/api/.env.example apps/api/.env
+cp apps/web/.env.example apps/web/.env
+
+# 2) Install dependencies
+pnpm install
+
+# 3) Start local infrastructure
+docker-compose up -d
+
+# 4) Apply DB schema
+pnpm -C apps/api db:push
 
+# 5) Start apps
+pnpm dev
 ```
-web: http://localhost:3000
-api: http://localhost:8080
-mailpit: http://localhost:8025
+
+## Default Local Endpoints
+
+```txt
+web:      http://localhost:3000
+api:      http://localhost:8080
+mailpit:  http://localhost:8025
 postgres: postgres://postgres:postgres@localhost:5432/postgres
-redis: redis://localhost:6379
-minio: http://localhost:9000
+valkey:   redis://localhost:6379
+rustfs:   http://localhost:9000
 ```
 
-## E2E Typesafety
+## Common Commands (Root)
 
-When developing applications with a smaller team(or solo) that tends to pivot, E2E typesafety is pretty imparative to develop with confidence. This stack acheives E2E type-safety through a few different means,
+```sh
+pnpm dev            # run web + api dev tasks via turbo
+pnpm build          # build all packages
+pnpm lint           # oxlint type-aware run
+pnpm lint:fix       # apply lint fixes
+pnpm typecheck      # turbo typecheck
+pnpm format         # oxfmt
+pnpm api:openapi:generate
+```
 
-1. A monorepo where types can be shared.
-2. OpenAPI(Swagger) docs actively generated.
-3. OpenAPI-Fetch client on the frontends.
+## End-to-End Type Safety
 
-**There is no need to regnerate types in the SojuStack, this is done automatically.** The only necessity is to ensure DTO's have their correct OpenAPI annotations.
+SojuStack keeps API and frontend contracts aligned by default:
 
-This is achieved by a non-blocking helper function that listens and regenerates the `openapi.d.ts` file upon any changes - instantly reflecting on all frontend clients. Go ahead, change an endpoint or DTO in NestJS and view the errors in the frontend clients.
+- Shared monorepo context
+- OpenAPI docs and generated type definitions
+- Typed API usage through `openapi-fetch`
 
-## Whats Inside and Why?
+In practice: update a DTO/route in API and frontend compile errors surface immediately where contracts changed.
 
-Hopefully this helps understand my logic and reasoning behind my choices in technology.
+## Why This Stack
 
 ### Axioms
 
 1. Does it solve the problem?
-2. Is it tested, stable, well documented, and battle-proven?
-3. No lock-in or ability to migrate away from the choice at anytime.
-4. Will it scale with my needs?
-5. Is the DX well thought out?
+2. Is it battle-tested and documented?
+3. Can I migrate away without pain?
+4. Does it scale with me?
+5. Is the developer experience actually good?
+6. Does it work well with AI(yeah, we're here so might as well)
 
 ### Backend
 
-#### NestJS (Framework)
+#### NestJS
 
-NestJS is the first to check all of the boxes above. It's on its v11 release, its proven itself for over a decade, it's incredibly easy to scale with many options available, and its documentation is fantastic.
+It checks all the boxes for me: mature, structured, testable, and easy to grow.  
+People call it verbose; I call it explicit. I prefer that when business logic gets real.
 
-It gets a bad rap in the node world for being verbose or from those who hate "OOP" in a "functional language". I for one embrace OOP in JS as it naturally documents your applications domain and business logic, keeps your application easily testable, and idk...its the way I mentally model things already so it translates well in my case. Also, have you ever written a monad?
+#### PostgreSQL
 
-Testability is also a massive incentive for building in NestJS. I'm not the largest fan of TDD or unit testing, but in some cases it sure does come in handy. And when you finally have the needs to write tests, you'll be thankful for an environment that makes it painless.
+I'm a relational DB person. Postgres has the right defaults and enough headroom that I rarely regret choosing it.
 
-#### Postgres (Database)
+#### Drizzle
 
-I'm a relational database type of guy. NoSQL databases have their role and place in the world but by large and whole you can't go wrong with Postgres. The only other real option is MySQL, which has some benefits, but in my experience I always end up wanting to reach for a feature or plugin it lacks.
+This is the SQL-first ORM experience I actually enjoy.  
+Minimal magic, typed queries, reviewable migrations, and no giant abstraction tax.
 
-#### Drizzle (ORM)
+#### Valkey (Redis-compatible cache)
 
-Drizzle is early, sure - but its also very, very, very simple. Its a query builder with migrations. I've had more confidence using Drizzle than the industry standard TypeORM by a long shot.
-If you know SQL, you know Drizzle and I like it for a few reasons,
+Simple, fast, and drop-in for Redis workflows.  
+With `Keyv` in the API layer, swapping providers is mostly config-level work.
 
-1. Its basic and simple; there is no magic. You write SQL like typescript and it generates pure SQL migrations to review. Infinite room to grow and no regrets to be had(ALWAYS REVIEW YOUR SQL MIGRATIONS MANUALLY, THIS IS TRUE FOR ANYTHING).
-2. It offers a type-safe, SQL-first approach that strikes an ideal balance between raw SQL flexibility and modern TypeScript ergonomics.
-3. It doesn't need an ecosystem like traditional ORMS. Its built to write sql and typesafe sql you shall write.
+#### Better Auth
 
-#### Redis (Cache)
+"Don't roll your own crypto" is still the rule.  
+Better Auth gives enough abstraction to move fast without boxing me in.
 
-Substitute this for ValKey if you wish. The cache manager in NestJS uses KeyV as an interface so the only migration needed is to change the URL.
+#### RustFS (S3-compatible object storage)
 
-#### Better-Auth (Auth)
+Local-first, self-hostable, and S3-compatible.  
+If I move to managed object storage later, it's mostly endpoint/credential changes.
 
-I'm a fan of "roll your own auth, not your own encryption". Its really not that hard to setup, but after evaluating Better-Auth I feel comfortable enough to include it as my auth solution. It does what I need it to do, provides an adequate level of abstraction, then gets out of the way. I've tested implementing better-auth then migrating away to a "self-rolled" auth and its **incredidbly** simple which gives me more confidence to build with it.
+### Frontend
 
-#### MinIO (Storage)
+#### TanStack Start + Router
 
-Minio is just self-hosted open source storage. Its fully S3 compatible so if you ever wanna switch over, its just a url change. The reason im a fan of MinIO is it keeps me out of the AWS console, lets me emulate my entire stack locally, and I can throw it on any VPS right next to my other services. Throw a CDN infront of it and it's quicker than S3.
+Fantastic routing model and good long-term ergonomics.  
+File-based routes + typed APIs make iteration fast and refactors safer.
 
-### Frontend
+#### TanStack Query
+
+The default for server state in React apps for a reason.
+
+#### shadcn + Base UI + Tailwind
+
+Composable primitives, easy customization, and no hard lock-in to a black-box UI kit.
 
-#### Tanstack Start (Framework)
+### Monorepo + Tooling
 
-I was hesitant to build ontop of this as its pre v1.0 release, but after seeing how far its come in such a short amount of time, the "breaking changes" guide being so incredibly well updated and documented, and its DX - its too good to let go.
+#### pnpm + Turbo
 
-This is the ONLY pre-release tech i'm willing to bet on for production at this time. I left for Svelte after seeing the direction of React and the horrific war-crimes Vercel/NextJS committed. TanStack Start brought me back to React.
+Fast workspace installs, clean task orchestration, and predictable monorepo workflows.
 
-#### Tanstack Query (Data Fetching)
+#### Oxlint + Oxfmt
 
-IDK what to say on this one, its obvious. If you remember what life was like before Tanstack Query having to fetch data with redux/thunks - you'd be a donator to the project like I am.
+Very fast lint/format feedback loops with type-aware checks where it matters.
 
-#### ShadCN (UI)
+#### Lefthook
 
-I have no preference in UI components. Use what you like and there's not really a wrong answer - this is purely what you enjoy and don't let anyone tell you differently. I use ShadCN for the same reasons i mentioned about every other tech above. It does what I need, gets out of my way when I want it to, and I can easily migrate away from it without fear of lock-in.
+Simple guardrails before push (`lint` + `typecheck`) so broken code is harder to ship.
