TalexDreamSoul/teatea-pension
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add Trellis planning and project specs

Browse Source
This commit is contained in:
admin
2026-07-01 06:27:55 -07:00
parent 7f227c5f2a
commit aafd9caaac
349 changed files with 55801 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

417
.trellis/spec/guides/cross-layer-thinking-guide.md Normal file
View File

@@ -0,0 +1,417 @@
# Cross-Layer Thinking Guide
> **Purpose**: Pre-implementation checklist for features that span multiple layers.
>
> **Core Principle**: 30 minutes of thinking saves 3 hours of debugging.
---
## When to Use This Guide
Use this guide when your feature:
- Touches 3+ layers (Server Component, Client Component, oRPC, Database)
- Involves data transformation between layers
- Has real-time or event-driven components
- Receives data from external sources (APIs, webhooks, file uploads)
---
## Pre-Implementation Checklist
Before writing code, answer these questions:
### 1. Layer Identification
**Which layers does this feature touch?**
- [ ] Server Components (RSC - data fetching, static rendering)
- [ ] Client Components (interactivity, browser APIs, React hooks)
- [ ] API Routes / oRPC Procedures (validation, business logic)
- [ ] Middleware (auth checks, redirects, header manipulation)
- [ ] Database (Drizzle ORM queries, migrations)
- [ ] Server Actions (form handling, progressive enhancement)
- [ ] External Services (third-party APIs, webhooks)
### 2. Data Flow Direction
**How does data flow?**
```
Read Flow: DB -> Drizzle -> oRPC Handler -> API Response -> React Query -> Component -> UI
Write Flow: UI -> Form/Action -> oRPC Mutation -> Handler -> Drizzle -> DB
SSR Flow: DB -> Drizzle -> oRPC Handler -> Server Component -> HTML -> Client Hydration
```
- [ ] Read-only (data flows from DB to UI)
- [ ] Write-only (data flows from UI to DB)
- [ ] Bidirectional (both directions)
- [ ] Server-rendered (data fetched in Server Components)
- [ ] Client-fetched (data fetched via React Query in Client Components)
### 3. Data Format at Each Layer
**What format is the data at each boundary?**
| Layer | Format | Example |
| ---------------- | ----------------------- | ----------------------------------------------- |
| Database | SQL types | `TEXT`, `INTEGER`, `TIMESTAMP`, `JSONB` |
| Drizzle ORM | TypeScript types | `string`, `number`, `Date`, `Record<>` |
| oRPC Handler | Zod-validated objects | `{ id: string, createdAt: Date }` |
| oRPC Response | Serialized JSON | `{ id: "abc", createdAt: "2024-01-01T..." }` |
| React Query | Cached response | Same as oRPC response (deserialized) |
| Server Component | Props (must serialize) | No functions, no Date objects, no class instances |
| Client Component | React state | Component props, hook return values |
| UI | Rendered output | HTML, Tailwind-styled elements |
### 3.1 Serialization Boundary (CRITICAL!)
**Design Principle**: Data crossing the Server/Client Component boundary must be serializable.
| Serializable (OK) | NOT Serializable (WILL BREAK) |
| ----------------------- | --------------------------------- |
| `string`, `number` | `Date` objects |
| `boolean`, `null` | `Map`, `Set` |
| Plain objects, arrays | Functions, class instances |
| `undefined` (as absent) | `BigInt`, `Symbol` |
**Common serialization trap**:
```typescript
// BAD - Date objects don't serialize across RSC boundary
async function ItemPage() {
const item = await orpcClient.items.get({ itemId: "123" });
// item.createdAt might be a Date object from Drizzle
return <ClientItem item={item} />; // Date becomes string or breaks!
}
// GOOD - Convert to serializable format before passing to Client Component
async function ItemPage() {
const item = await orpcClient.items.get({ itemId: "123" });
return <ClientItem item={{
...item,
createdAt: item.createdAt.toISOString(), // Explicit string conversion
}} />;
}
```
### 4. Data Transformation Points
**Where does format change? Who is responsible?**
| From | To | Transformer | Location |
| ----------------- | ------------------- | ------------------- | -------------------------- |
| DB timestamp | JS Date | Drizzle ORM | Automatic |
| JS Date | ISO string | oRPC serialization | API response |
| ISO string | Display string | React component | UI layer |
| User input | Validated data | Zod schema | oRPC input validation |
| JSONB column | TypeScript object | Drizzle + cast | Query layer |
### 5. Boundary Questions (Critical!)
For each layer boundary, ask:
**RSC / Client Component Boundary:**
- What data is the Server Component passing as props?
- Is all of it serializable? (no functions, no Date objects, no Maps)
- Could this data be fetched directly in the Client Component via React Query instead?
- Does the Client Component need to refetch or mutate this data?
**Client Component / oRPC Boundary:**
- What format does the oRPC response return?
- How does React Query cache and deserialize it?
- What happens if the response format changes?
- Are query keys consistent for cache invalidation?
**oRPC Handler / Database Boundary:**
- Are timestamps handled consistently? (ISO strings vs Date objects)
- Are IDs strings or numbers?
- What about null vs undefined?
- Does Drizzle transform types automatically?
- Are JSONB columns properly cast?
**Middleware / Route Boundary:**
- Is auth checked in middleware, oRPC procedure, or both?
- What happens if middleware redirects but the API call continues?
- Are headers properly forwarded in SSR context?
### 6. Authentication Context
**Where is auth available?**
| Layer | Auth Method | Notes |
| ---------------- | -------------------------------------- | --------------------------------------- |
| Middleware | `getSession()` from headers/cookies | Runs before route handler |
| Server Component | `getSession()` or `auth()` helper | Can redirect on the server |
| Client Component | `useSession()` hook | May need loading state |
| oRPC Procedure | `protectedProcedure` middleware | Throws UNAUTHORIZED if no session |
| API Route | `getSession()` from request headers | Manual check needed |
**Common auth pitfall**:
```typescript
// BAD - Auth checked in middleware but not in oRPC procedure
// If someone calls the API directly, auth is bypassed!
export const middleware = NextResponse.next(); // auth check here
export const getSecret = publicProcedure.handler(...); // no auth check!
// GOOD - Auth in oRPC procedure (always enforced)
export const getSecret = protectedProcedure.handler(...);
```
### 7. Edge Cases
- [ ] What if the data is empty/null?
- [ ] What if the database query fails?
- [ ] What if the oRPC call times out?
- [ ] What if a referenced entity doesn't exist?
- [ ] What if the user navigates away mid-mutation?
- [ ] What if React Query returns stale data?
- [ ] What if the user's session expires mid-operation?
- [ ] What if the same mutation fires twice (double-click)?
---
## Common Patterns
### Pattern A: Server Component Data Fetch
**Layers**: Server Component -> oRPC Client -> Handler -> Database
**Data Flow**:
```
1. Server Component: Calls oRPC client directly (server-side)
2. oRPC Handler: Validates auth, queries database
3. Drizzle: Returns typed results
4. Server Component: Renders HTML with data
5. Client: Receives pre-rendered HTML
```
**Common Issues**:
- **Serialization**: Server Components can render Date objects directly, but cannot pass them as props to Client Components
- **No cache**: Server-side oRPC calls bypass React Query cache; consider prefetching
- **Waterfall**: Sequential server-side calls create request waterfalls; use `Promise.all` for parallel fetching
### Pattern B: Client Component with React Query
**Layers**: Client Component -> React Query -> oRPC Client -> Handler -> Database
**Data Flow**:
```
1. Client Component: Mounts, triggers useQuery
2. React Query: Checks cache, calls oRPC client if stale
3. oRPC Client: Sends HTTP request to API route
4. oRPC Handler: Validates input/auth, queries DB
5. Response: JSON back through React Query
6. Client Component: Re-renders with data
```
**Common Issues**:
- **Loading states**: Must handle `isLoading`, `isError`, `isPending` properly
- **Stale data**: Configure `staleTime` and `gcTime` appropriately
- **Cache invalidation**: Use `orpc.xxx.key()` for consistent invalidation after mutations
- **Enabled flag**: Disable queries when required parameters are missing
### Pattern C: Mutation with Optimistic Update
**Layers**: Client Component -> useMutation -> oRPC Client -> Handler -> Database
**Data Flow**:
```
1. User: Triggers action (click, form submit)
2. onMutate: Optimistically update React Query cache
3. oRPC Client: Sends mutation request
4. Handler: Validates, writes to DB
5. onSuccess: Invalidate related queries
6. onError: Rollback optimistic update from snapshot
```
**Common Issues**:
- **Rollback complexity**: Must snapshot all affected queries before optimistic update
- **Type safety**: Cache manipulation needs explicit type annotations
- **Race conditions**: Cancel outgoing refetches before optimistic update (`cancelQueries`)
- **Partial failures**: Batch operations may partially succeed
### Pattern D: Server Action (Form Handling)
**Layers**: Form -> Server Action -> oRPC Client / DB -> Revalidate
**Data Flow**:
```
1. User: Submits form
2. Server Action: Receives FormData, validates
3. Action: Calls oRPC client or DB directly
4. Action: Calls revalidatePath/revalidateTag
5. Page: Re-renders with updated data
```
**Common Issues**:
- **Progressive enhancement**: Forms work without JS when using Server Actions
- **Validation**: Validate on both client (UX) and server (security)
- **Redirect vs revalidate**: Choose the right post-action behavior
- **Error handling**: Server Action errors need proper error boundaries
### Pattern E: Middleware + API Route Auth
**Layers**: Request -> Middleware -> API Route / oRPC -> Handler
**Data Flow**:
```
1. Request: Arrives at Next.js server
2. Middleware: Checks auth, may redirect to login
3. API Route: Handles oRPC request
4. oRPC Middleware: Validates session (protectedProcedure)
5. Handler: Executes business logic
```
**Common Issues**:
- **Double auth check**: Middleware protects pages, oRPC protects API; both are needed
- **Header forwarding**: SSR requests must forward cookies/headers to oRPC client
- **Middleware scope**: Don't run auth middleware on public assets or API routes that handle their own auth
---
## Lessons from Common Bugs
| Bug | Root Cause | Prevention |
| ------------------------------- | --------------------------------------------------------- | --------------------------------------------------- |
| `Date` props break hydration | Date objects passed from Server to Client Component | Convert to ISO string before passing as props |
| Stale data after mutation | Forgot to invalidate React Query cache | Always invalidate with `orpc.xxx.key()` in onSuccess |
| Auth bypass on API | Auth only in middleware, not in oRPC procedure | Always use `protectedProcedure` for protected data |
| `BigInt` serialization error | Database returns BigInt, JSON.stringify fails | Cast to number or string before response |
| Query fires with null ID | `enabled` flag not set on conditional queries | Always guard with `enabled: !!requiredParam` |
| Cache key mismatch | Manual query key doesn't match oRPC generated key | Always use `orpc.xxx.key()` or `orpc.xxx.queryKey()` |
| N+1 queries in handler | Fetching related data in a loop | Use `inArray()` for batch queries |
| Hydration mismatch | Server and client render different output (e.g., locale) | Ensure consistent data between server and client |
| Headers not forwarded in SSR | oRPC client doesn't forward cookies in server context | Configure client to forward headers in SSR mode |
---
## Checklist Template
Copy this for your feature:
```markdown
## Feature: [Name]
### Layers Involved
- [ ] Server Component
- [ ] Client Component
- [ ] oRPC Procedure
- [ ] Middleware
- [ ] Database
- [ ] Server Action
- [ ] External Service
### Data Flow
[Describe the flow]
### Format at Each Layer
| Layer | Format |
| ----- | ------ |
| ... | ... |
### Transformation Points
| From | To | Who |
| ---- | --- | --- |
| ... | ... | ... |
### Auth Strategy
- Middleware: [yes/no, what it checks]
- oRPC: [publicProcedure/protectedProcedure/adminProcedure]
### Edge Cases Considered
- [ ] Empty/null data
- [ ] Invalid format / serialization
- [ ] Operation failure / timeout
- [ ] User cancellation / navigation
- [ ] Session expiry mid-operation
- [ ] Double submission
```
---
## Cross-Layer Review Mindset
### The Comparison Trap
**Wrong thinking**: "This line wasn't changed, so it must be correct."
```
Comparison thinking (surface level):
Before: new Date() -> After: new Date() -> "No change, must be fine"
Global thinking (design level):
Design intent: ISO strings across RSC boundary -> Current: Date object -> "This is a bug"
```
**Key insight**: Review validates "system state is correct", not just "change is correct".
### Data Outlet Checklist
Every review must cover ALL data outlets:
```
Data Outlets:
|-- oRPC Response (handler -> client)
|-- Server Component Props (RSC -> Client Component)
|-- React Query Cache (shared across components)
|-- URL State (nuqs, searchParams)
|-- Server Action Return (action -> form)
|-- Any external interface
```
Ask: **"Is the format correct at EACH outlet?"**
### Review Three Questions
Before finishing any cross-layer review:
1. **Outlet Question**: Have I checked ALL data outlets, not just the "core" one?
2. **Design Question**: Does existing code match design principles? (Not "is the change correct?")
3. **Checklist Question**: Could my checklist itself be wrong?
### Validation vs Verification
| Approach | Focus | Risk |
| --------------- | ---------------------------- | ------------------------------------ |
| **Incremental** | "Is this change correct?" | Misses pre-existing bugs |
| **Global** | "Is the system correct now?" | More thorough, catches legacy issues |
Always prefer global verification for cross-layer features.
---
## When Things Go Wrong
If you encounter a cross-layer bug:
1. **Identify the boundary** - Where exactly does it fail?
2. **Log at boundaries** - Add logging before and after each transformation
3. **Check assumptions** - What format did you expect vs what you got?
4. **Test in isolation** - Can you reproduce with a simple test case?
5. **Document the fix** - Add to "Lessons from Common Bugs" table
---
**Language**: All documentation should be written in **English**.