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

125
.trellis/spec/frontend/index.md Normal file
View File

@@ -0,0 +1,125 @@
# Next.js Frontend Development Guidelines
> Universal frontend development guidelines for Next.js full-stack applications with React + TypeScript + TailwindCSS.
## Tech Stack
- **Framework**: Next.js 15, React 19
- **Language**: TypeScript (strict mode)
- **Styling**: TailwindCSS 4, Radix UI
- **API**: oRPC (OpenAPI RPC), React Query (TanStack Query)
- **URL State**: nuqs
- **Auth**: better-auth
- **AI**: Vercel AI SDK (@ai-sdk/react)
---
## Documentation Files
| File | Description | Priority |
| ---------------------------------------------------- | ---------------------------------------------------- | ------------- |
| [components.md](./components.md) | Server/Client components, semantic HTML, next/image | **Must Read** |
| [authentication.md](./authentication.md) | better-auth client, session, protected routes | **Must Read** |
| [orpc-usage.md](./orpc-usage.md) | Type-safe API calls, React Query integration | **Must Read** |
| [hooks.md](./hooks.md) | Query and mutation hook patterns | Reference |
| [api-integration.md](./api-integration.md) | oRPC client, real-time, AI streaming | Reference |
| [state-management.md](./state-management.md) | URL state with nuqs, React Context patterns | Reference |
| [directory-structure.md](./directory-structure.md) | Project structure and module conventions | Reference |
| [type-safety.md](./type-safety.md) | TypeScript guidelines, type inference, Zod | Reference |
| [css-layout.md](./css-layout.md) | CSS patterns, flexbox, responsive, touch | Reference |
| [ai-sdk-integration.md](./ai-sdk-integration.md) | useChat hook, streaming, tool call handling | Reference |
| [quality.md](./quality.md) | Pre-commit checklist and code quality standards | Reference |
---
## Quick Navigation by Task
### Before Starting Development
| Task | Document |
| --------------------------------- | -------------------------------------------------- |
| Understand project structure | [directory-structure.md](./directory-structure.md) |
| Learn Server vs Client components | [components.md](./components.md) |
| Set up authentication | [authentication.md](./authentication.md) |
### During Development
| Task | Document |
| --------------------------- | -------------------------------------------------- |
| Make type-safe API calls | [orpc-usage.md](./orpc-usage.md) |
| Create custom hooks | [hooks.md](./hooks.md) |
| Manage application state | [state-management.md](./state-management.md) |
| Build UI components | [components.md](./components.md) |
| Ensure type safety | [type-safety.md](./type-safety.md) |
| Integrate AI features | [ai-sdk-integration.md](./ai-sdk-integration.md) |
| Handle CSS & layout | [css-layout.md](./css-layout.md) |
### Before Committing
| Task | Document |
| ----------------------- | -------------------------------- |
| Run quality checklist | [quality.md](./quality.md) |
| Verify CSS in both envs | [css-layout.md](./css-layout.md) |
| Check type safety | [type-safety.md](./type-safety.md) |
---
## Core Rules Summary
| Rule | Reference |
| ------------------------------------------------------------ | -------------------------------------------------- |
| **Default to Server Components** | [components.md](./components.md) |
| **Use `<button>` for clickable actions, not `<div>`** | [components.md](./components.md) |
| **Always use `next/image` instead of `<img>`** | [components.md](./components.md) |
| **Import types from backend, never redefine them** | [type-safety.md](./type-safety.md) |
| **No `any` types or `@ts-expect-error` in new code** | [type-safety.md](./type-safety.md) |
| **Use oRPC client for API calls (not raw fetch)** | [orpc-usage.md](./orpc-usage.md) |
| **Use oRPC generated query keys (not manual strings)** | [orpc-usage.md](./orpc-usage.md) |
| **Store shareable state in URL with nuqs** | [state-management.md](./state-management.md) |
| **Use `items-stretch` on main flex containers** | [css-layout.md](./css-layout.md) |
| **Handle both tool call formats (streaming + history)** | [ai-sdk-integration.md](./ai-sdk-integration.md) |
| **Always check session loading state before rendering** | [authentication.md](./authentication.md) |
---
## Architecture Overview
```
+--------------------------------------------------------------+
| Next.js Application |
| |
| app/ modules/ |
| ├── (marketing)/ ├── [feature]/ |
| │ └── [locale]/ │ ├── components/ |
| └── (app)/ │ ├── hooks/ |
| └── [routes]/ │ ├── context/ |
| │ └── lib/ |
| ├── shared/ |
| └── ui/ |
+-------------------------------+------------------------------+
|
oRPC (type-safe RPC) | React Query (cache)
|
+-------------------------------+------------------------------+
| API Layer (Server) |
| +--------------+ +----------------+ +------------------+ |
| | oRPC | | better-auth | | AI SDK | |
| | Router | | Sessions | | Streaming | |
| +--------------+ +----------------+ +------------------+ |
+--------------------------------------------------------------+
```
---
## Getting Started
1. **Read the Must-Read documents** - Components, authentication, and oRPC usage
2. **Set up your project structure** - Follow [directory-structure.md](./directory-structure.md)
3. **Configure TypeScript paths** - See [type-safety.md](./type-safety.md)
4. **Set up API client** - Use patterns from [orpc-usage.md](./orpc-usage.md)
5. **Build components** - Follow [components.md](./components.md) and [hooks.md](./hooks.md)
6. **Before committing** - Complete the [quality.md](./quality.md) checklist
---
**Language**: All documentation is written in **English**.