init

Author: yunbow

.github/mlc_config.json

@@ -0,0 +1,8 @@
+{
+  "ignorePatterns": [
+    { "pattern": "^https://github.com/yunbow/" }
+  ],
+  "timeout": "10s",
+  "retryOn429": true,
+  "aliveStatusCodes": [200, 206, 301, 302, 403]
+}

.github/workflows/lint.yml

@@ -0,0 +1,39 @@
+name: Lint & Link Check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  markdown-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DavidAnson/markdownlint-cli2-action@v19
+        with:
+          globs: "**/*.md"
+          config: |
+            {
+              "MD013": false,
+              "MD033": false,
+              "MD041": false
+            }
+
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          use-quiet-mode: 'yes'
+          config-file: '.github/mlc_config.json'
+
+  yaml-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check YAML/JSON syntax
+        run: |
+          find . -name "*.json" -not -path "./.git/*" -exec python3 -c "import json,sys; json.load(open(sys.argv[1]))" {} \;

.gitignore

@@ -0,0 +1,19 @@
+# OS
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# AI coding tools (user-local config — not part of this repo)
+.claude/
+CLAUDE.md
+.kiro/
+AGENTS.md
+.cursor/
+.cursorrules

01_philosophy/anti-patterns.md

@@ -0,0 +1,188 @@
+$NOTE
+# Anti-Patterns
+
+This defines repeatedly observed "do not do this" patterns.
+Each anti-pattern includes why it is problematic and what should be done instead.
+
+---
+
+## 1. Abandoning Type Safety
+
+### Careless Use of `any`
+
+```ts
+// ❌ Creates a hole in the type system
+const data: any = await fetchData()
+data.nonExistent.property // Explodes at runtime
+
+// ✔ unknown + type guard
+const data: unknown = await fetchData()
+if (isValidResponse(data)) {
+  data.property // Type-safe
+}
+```
+
+**Why it's problematic**: `any` disables type checking. A single `any` propagates through type inference — when `any` is assigned to a variable, every expression derived from it also becomes `any`, silently disabling checks across the entire call chain without compiler warnings.
+**Exception**: Inadequate type definitions in external libraries. Always attach a `// FIXME` comment.
+
+---
+
+## 2. Architectural Deviation
+
+### Direct fetch from Components
+
+```ts
+// ❌ Skipping layers
+function MyComponent() {
+  const [data, setData] = useState(null)
+  useEffect(() => {
+    fetch('/api/data').then(r => r.json()).then(setData)
+  }, [])
+}
+
+// ✔ Go through Server Actions + Hooks
+function MyComponent() {
+  const { data } = useListData({ action: fetchDataAction })
+}
+```
+
+**Why it's problematic**: Error handling, authentication, caching, and loading states end up implemented inconsistently.
+
+### Introducing Global State Management Libraries
+
+```ts
+// ❌ Introducing Redux / Zustand / Recoil
+const useStore = create((set) => ({ ... }))
+
+// ✔ Server Actions + local state + Feature Context
+const [state, setState] = useState(initial)
+// or
+const { value } = useFeatureContext()
+```
+
+**Why it's problematic**: Global state obscures the origin of data and undermines Server Actions' role as the source of truth.
+
+---
+
+## 3. Lack of Observability
+
+### Missing Trace ID
+
+```ts
+// ❌ Cannot identify which request caused the error
+logger.error('Something went wrong')
+
+// ✔ Traceable via Request ID
+logger.error({ requestId, userId, action }, 'Payment processing failed')
+```
+
+**Why it's problematic**: Without it, requests cannot be traced end-to-end during incident investigation.
+
+---
+
+## 4. Over-Abstraction
+
+### Generalizing Code Used in Only One Place
+
+```ts
+// ❌ Abstraction with no reuse potential
+function useSinglePurposeHook() { ... }
+function createSingleUseFactory(options) { ... }
+
+// ✔ Write it inline. Extract only after duplication appears in 3 places
+```
+
+**Why it's problematic**: Abstraction increases comprehension cost. An abstraction used in only one place leaves only the cost.
+
+### Bloated Configuration Objects
+
+```ts
+// ❌ Too many options = the abstraction is heading in the wrong direction
+createAction({
+  schema, handler, middleware, errorHandler,
+  retryPolicy, cachePolicy, rateLimitPolicy, auditPolicy,
+})
+
+// ✔ Extract only the common parts; implement special cases individually
+const baseAction = createBaseAction(commonOptions)
+const specialAction = async (input) => {
+  // Special logic
+  return baseAction(transformedInput)
+}
+```
+
+**Why it's problematic**: A massive configuration object is not "flexible" — it is "complex."
+
+---
+
+## 5. Misuse of Naming and Comments
+
+### Vague Naming
+
+```ts
+// ❌
+const data = await getData()
+const result = process(data)
+function handleClick() { ... }
+
+// ✔
+const userProfile = await fetchUserProfile()
+const validatedOrder = validateOrder(rawOrder)
+function handleSubmitPayment() { ... }
+```
+
+**Why it's problematic**: `data`, `result`, `handle` convey nothing. The reader must read the implementation to understand the intent.
+
+### Comments That Explain Logic
+
+```ts
+// ❌ Stating what the code already says
+// Check if user's age is 18 or above
+if (user.age >= 18) { ... }
+
+// ✔ Document intent, exceptions, and side effects
+// Legal requirement: minors cannot use the payment feature (see compliance guidelines)
+if (user.age >= 18) { ... }
+```
+
+**Why it's problematic**: "What it does" is told by the code. Comments should tell "why it does it that way."
+
+---
+
+## 6. Inadequate Testing
+
+### Testing Only the Happy Path
+
+```ts
+// ❌ Only the success case
+test('creates user', async () => {
+  const user = await createUser(validInput)
+  expect(user).toBeDefined()
+})
+
+// ✔ Include error cases, boundary values, and security scenarios
+test('rejects invalid email', ...)
+test('prevents IDOR access', ...)
+test('handles duplicate webhook events', ...)
+test('fails gracefully on external API timeout', ...)
+```
+
+**Why it's problematic**: Bugs occur in error cases and at boundary values, not in the happy path.
+
+---
+
+## 7. Ignoring Performance
+
+### Huge Bundle Sizes
+
+```ts
+// ❌ Importing the entire library
+import _ from 'lodash'
+import moment from 'moment'
+
+// ✔ Import only the needed functions / use lightweight alternatives
+import { debounce } from 'lodash/debounce'
+import dayjs from 'dayjs'
+```
+
+**Why it's problematic**: Bundle size directly impacts load time. As a reference point, research by Google and Akamai shows that each additional 100KB of JavaScript adds roughly 100–300ms of parse/compile time on mobile devices, and pages loading in over 3 seconds see significantly higher bounce rates. Tree-shaking and selective imports keep the bundle lean.

01_philosophy/mental-models.md

@@ -0,0 +1,110 @@
+$NOTE
+# Mental Models
+
+This defines the thinking patterns behind design decisions.
+These are not concrete rules, but the "way of thinking" from which rules emerge.
+
+---
+
+## 1. Constraints Breed Creativity
+
+**"Fewer choices lead to faster and better decisions."**
+
+"Faster" here means reduced decision fatigue and shorter code review cycles. When the framework constrains choices (e.g., "no Enums, use union literals"), developers spend zero time debating the approach and reviewers can focus on logic rather than style. This compounds across a team — eliminating 10 micro-decisions per PR across 50 PRs/week saves meaningful cognitive load.
+
+- `strict: true` doesn't take away freedom — it takes away room for bugs
+- Tailwind's utility classes don't restrict expression — they guarantee consistency
+- "No Enums," "No any," "No console.log" are constraints that raise the quality floor
+
+> Unlimited freedom produces unlimited inconsistency.
+
+---
+
+## 2. Code is Read More Than Written
+
+**"Write code that the future reader (including yourself 3 months later) can understand as quickly as possible."**
+
+- Write code where intent is clear, rather than optimizing for brevity or shortness
+- Consistency in naming conventions directly impacts searchability and refactoring ease
+- Don't use comments to explain logic. Only document intent, side effects, and edge cases
+
+> The code should convey not "what it does" but "why it does it this way."
+
+---
+
+## 3. Validate at Boundaries
+
+**"Trust the internals, but validate strictly at the points of contact with the outside."**
+
+```
+External Input ──[Zod]──▶ Server Action ──[Types]──▶ Business Logic ──[ORM]──▶ DB
+              ↑ Guard here                ↑ Protected by types here
+```
+
+- User input, API requests, webhooks, environment variables — all are "external"
+- Once data passes validation, trust the types internally
+- Don't over-apply defensive programming inside internal code (types provide the guarantee)
+
+---
+
+## 4. Design for Failure
+
+**"Don't write code that assumes things work. Design with the assumption that things break."**
+
+- All external communication can fail (timeouts, rate limits, service outages)
+- Use types to prevent forgetting error handling (discriminated union `ActionResult<T>`)
+- Design so that non-critical feature failures don't take down critical features. To distinguish: **critical features** are those whose failure prevents the user from completing the core task they came to do (e.g., authentication, checkout, data saving). **Non-critical features** are enhancements that improve the experience but whose absence doesn't block the core workflow (e.g., analytics, notifications, recommendations, avatar display). When in doubt, ask: "Can the user still accomplish their primary goal without this feature?"
+- Distinguish between retryable and non-retryable errors
+
+> Testing only the happy path is like selling umbrellas only on sunny days.
+
+---
+
+## 5. Unidirectional Data Flow
+
+**"If the data flow is consistent, most bugs disappear."**
+
+```
+Server Actions (commands)
+       ↓
+    Hooks (state management / side-effect control)
+       ↓
+  Components (rendering / event firing)
+       ↓
+    Callbacks (events bubble up)
+       ↓
+Server Actions (next command)
+```
+
+- Data flows down (Props), events flow up (Callbacks)
+- Do not use global state management libraries (Redux, Zustand, etc.)
+- Server Actions are the single source of truth. Hooks are thin coordination layers
+
+> Two-way data binding is convenient in small apps but creates chaos in large ones.
+
+---
+
+## 6. Rule of Three (Timing of Abstraction)
+
+**"Premature abstraction leads to wrong abstraction."**
+
+| Occurrences | Action |
+|-------------|--------|
+| 1 place | Write it inline — you have no evidence of a pattern yet |
+| 2 places | Extract to a helper function if the logic is identical — but remain skeptical; two instances may be coincidentally similar |
+| 3+ places | Extract to a factory function if the pattern is identical — three occurrences give enough evidence to identify the true common pattern and design a stable interface |
+| 5+ places | Consider creating a base component if the components are similar — at this scale the maintenance cost of duplication exceeds the comprehension cost of abstraction |
+
+- An abstraction used in only one place only adds comprehension cost
+- If the configuration object keeps growing, it's a sign the abstraction is heading in the wrong direction
+
+---
+
+## 7. Make the Implicit Explicit
+
+**"Implicit agreements become bugs the moment the team changes."**
+
+- Make side effects clear through naming (`fetchUser()` = has side effects, `calculatePrice()` = pure)
+- Always include a reason with `eslint-disable`
+- Make technical debt visible with `FIXME` comments — don't leave it untracked
+- Convey intent through naming convention suffixes and prefixes (`*-actions.ts`, `use*`, `create*Schema`)