@amirulabu/create-recurring-rabbit-app 0.0.0-alpha

package/templates/default/docs/architecture.md

@@ -0,0 +1,241 @@
+# Architecture Overview
+
+## System Design
+
+This project follows a **type-safe, full-stack architecture** where types flow seamlessly from database schema to UI components.
+
+### Data Flow
+
+```
+Database Schema (Drizzle) → tRPC Procedures → React Components
+```
+
+1. **Database layer** defines the source of truth for data types
+2. **tRPC procedures** operate on typed database queries
+3. **React components** receive fully typed data without manual interfaces
+
+### Key Architectural Decisions
+
+#### Why TanStack Start over Next.js?
+
+- **Better TypeScript integration** with less configuration
+- **File-based routing** without App Router complexity
+- **Smaller bundle size** for micro-SaaS use cases
+- **Simpler mental model** for developers
+
+#### Why Better-auth over NextAuth?
+
+- **Simpler configuration** for basic email/password auth
+- **Better TypeScript support** with fewer generic type issues
+- **Database session storage** built-in for scalability
+- **Less overhead** for simple authentication needs
+
+#### Why Drizzle over Prisma?
+
+- **Zero runtime overhead** with compile-time query building
+- **Better migration control** with SQL-first approach
+- **Lighter weight** for simple SaaS data models
+- **Type-safe queries** without code generation
+
+## Security Patterns
+
+### Authentication Flow
+
+1. User registers with email/password
+2. Email verification required before dashboard access
+3. Sessions stored in database with automatic cleanup
+4. CSRF protection enabled on all authenticated routes
+
+### Environment Variable Management
+
+- Server-only variables never accessible to client
+- Type-safe validation with immediate feedback
+- Auto-generation of secure secrets during setup
+
+### Route Protection
+
+Protected routes use `beforeLoad` guards to check authentication:
+
+```typescript
+export const Route = createFileRoute('/dashboard')({
+  beforeLoad: ({ context }) => {
+    if (!context.auth.user) {
+      throw redirect({ to: '/auth/login' })
+    }
+  },
+  component: Dashboard,
+})
+```
+
+## Performance Considerations
+
+### Database Optimization
+
+- SQLite for development (zero-config, fast iteration)
+- Connection pooling configured for Postgres production
+- Indexes on frequently queried columns (user lookups)
+
+### Frontend Optimization
+
+- Automatic code splitting with TanStack Start
+- Optimistic updates with TanStack Query
+- CSS-in-JS avoided for better bundle size
+- Lazy loading of routes
+
+## Server-Side Organization
+
+### tRPC Structure
+
+```
+src/server/api/
+├── root.ts         # Main router combining all sub-routers
+├── trpc.ts         # tRPC configuration, context, middleware
+├── routers/
+│   ├── user.ts      # User management procedures
+│   └── dashboard.ts # Dashboard data procedures
+```
+
+### Authentication Structure
+
+```
+src/server/auth/
+└── config.ts       # Better-auth configuration with Drizzle adapter
+```
+
+### Database Structure
+
+```
+src/server/db/
+├── index.ts        # Database connection factory
+├── schema.ts       # Drizzle schema definitions
+├── migrate.ts      # Migration runner
+└── seed.ts        # Database seeding
+```
+
+## Client-Side Organization
+
+### Routes (TanStack Start)
+
+```
+src/app/
+├── __root.tsx      # Root layout with providers
+├── index.tsx       # Landing page
+├── auth/           # Authentication routes
+│   ├── login.tsx
+│   └── register.tsx
+└── dashboard/       # Protected dashboard routes
+    ├── index.tsx
+    └── settings.tsx
+```
+
+### Components
+
+```
+src/components/
+├── ui/             # Reusable shadcn/ui components
+├── layout/         # Layout components (header, sidebar)
+└── features/        # Feature-specific components
+    └── auth/        # Authentication forms
+```
+
+### Shared Utilities
+
+```
+src/lib/
+├── api.ts          # tRPC client setup
+├── auth.ts         # Better-auth React client
+├── email.ts        # Resend email integration
+├── env.ts          # Environment validation
+└── utils.ts        # Shared utility functions
+```
+
+## Type Flow Example
+
+### Database Schema
+
+```typescript
+export const users = sqliteTable('users', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  email: text('email').notNull(),
+})
+```
+
+### tRPC Procedure
+
+```typescript
+export const userRouter = router({
+  getProfile: protectedProcedure.query(async ({ ctx }) => {
+    return ctx.db.select().from(users).where(eq(users.id, ctx.user.id))
+  }),
+})
+```
+
+### React Component
+
+```typescript
+function UserProfile() {
+  const { data: user } = api.user.getProfile.useQuery()
+
+  return <div>{user?.name}</div>
+}
+```
+
+Types automatically flow from schema → tRPC → React without manual interfaces.
+
+## Scaling Patterns
+
+### Adding New Features
+
+When adding new features, follow these patterns:
+
+1. **Database**: Add table to `schema.ts`, generate migration
+2. **tRPC**: Create router with procedures, add to root router
+3. **UI**: Create components in `features/`, add routes in `app/`
+4. **Types**: No manual types needed - everything inferred from database
+
+### Multi-Tenancy (Future)
+
+The architecture supports future multi-tenancy:
+
+- Add `organizationId` foreign key to user tables
+- Add organization procedures to tRPC routers
+- Filter queries by organization context
+
+### Background Jobs (Future)
+
+For background jobs, consider:
+
+- Add job queue (BullMQ, Agenda)
+- Create worker processes
+- Store job state in database
+
+## Monitoring & Debugging
+
+### Development Tools
+
+- **tRPC DevTools**: Inspect API calls in browser
+- **Drizzle Studio**: Visual database browser
+- **React DevTools**: Component tree inspection
+- **TanStack Query DevTools**: Query state inspection
+
+### Logging
+
+- Slow query logging in development
+- Request logging in tRPC middleware
+- Error tracking (can add Sentry)
+
+## Deployment Architecture
+
+### Development
+
+- SQLite database in `data/` directory
+- Hot reload with Vinxi
+- Environment variables from `.env.local`
+
+### Production
+
+- PostgreSQL database (connection pooling configured)
+- Static assets cached by platform (Vercel, Railway)
+- Environment variables from platform dashboard
+- Build artifacts optimized (code splitting, tree shaking)

package/templates/default/docs/database.md

@@ -0,0 +1,376 @@
+# Database Schema
+
+## Overview
+
+This project uses Drizzle ORM with SQLite for development and PostgreSQL for production. All tables are defined in `src/server/db/schema.ts`.
+
+## Tables
+
+### users
+
+Stores user account information with email verification status.
+
+| Column        | Type            | Description                   |
+| ------------- | --------------- | ----------------------------- |
+| id            | text (PK)       | Unique user identifier (CUID) |
+| name          | text            | User's display name           |
+| email         | text            | User's email address (unique) |
+| emailVerified | boolean         | Email verification status     |
+| image         | text (optional) | Profile image URL             |
+| createdAt     | timestamp       | Account creation time         |
+| updatedAt     | timestamp       | Last update time              |
+
+```typescript
+export const users = sqliteTable('users', {
+  id: text('id')
+    .primaryKey()
+    .$defaultFn(() => createId()),
+  name: text('name').notNull(),
+  email: text('email').notNull(),
+  emailVerified: integer('email_verified', { mode: 'boolean' }).default(false),
+  image: text('image'),
+  createdAt: integer('created_at', { mode: 'timestamp' }).$defaultFn(
+    () => new Date()
+  ),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).$defaultFn(
+    () => new Date()
+  ),
+})
+```
+
+### sessions
+
+Stores active user sessions for authentication.
+
+| Column    | Type      | Description                      |
+| --------- | --------- | -------------------------------- |
+| id        | text (PK) | Unique session identifier (CUID) |
+| userId    | text (FK) | Reference to users table         |
+| expiresAt | timestamp | Session expiration time          |
+| token     | text      | Session token                    |
+
+```typescript
+export const sessions = sqliteTable('sessions', {
+  id: text('id')
+    .primaryKey()
+    .$defaultFn(() => createId()),
+  userId: text('user_id')
+    .references(() => users.id, { onDelete: 'cascade' })
+    .notNull(),
+  expiresAt: integer('expires_at', { mode: 'timestamp' }).notNull(),
+  token: text('token').notNull(),
+})
+```
+
+### accounts
+
+Stores OAuth provider accounts (for future integration with Google, GitHub, etc.).
+
+| Column     | Type      | Description                           |
+| ---------- | --------- | ------------------------------------- |
+| id         | text (PK) | Unique account identifier (CUID)      |
+| userId     | text (FK) | Reference to users table              |
+| accountId  | text      | Provider account ID                   |
+| providerId | text      | OAuth provider (google, github, etc.) |
+
+```typescript
+export const accounts = sqliteTable('accounts', {
+  id: text('id')
+    .primaryKey()
+    .$defaultFn(() => createId()),
+  userId: text('user_id')
+    .references(() => users.id, { onDelete: 'cascade' })
+    .notNull(),
+  accountId: text('account_id').notNull(),
+  providerId: text('provider_id').notNull(),
+})
+```
+
+### verifications
+
+Stores email verification and password reset tokens.
+
+| Column     | Type      | Description                           |
+| ---------- | --------- | ------------------------------------- |
+| id         | text (PK) | Unique verification identifier (CUID) |
+| identifier | text      | Email address                         |
+| value      | text      | Verification code/token               |
+| expiresAt  | timestamp | Token expiration time                 |
+
+```typescript
+export const verifications = sqliteTable('verifications', {
+  id: text('id')
+    .primaryKey()
+    .$defaultFn(() => createId()),
+  identifier: text('identifier').notNull(),
+  value: text('value').notNull(),
+  expiresAt: integer('expires_at', { mode: 'timestamp' }).notNull(),
+})
+```
+
+## Relationships
+
+### users → sessions
+
+One-to-many relationship: A user can have multiple sessions.
+
+```typescript
+export const usersRelations = relations(users, ({ many }) => ({
+  sessions: many(sessions),
+}))
+```
+
+### users → accounts
+
+One-to-many relationship: A user can have multiple OAuth accounts.
+
+```typescript
+export const usersRelations = relations(users, ({ many }) => ({
+  accounts: many(accounts),
+}))
+```
+
+### users → verifications
+
+One-to-many relationship: A user can have multiple verification tokens.
+
+```typescript
+export const usersRelations = relations(users, ({ many }) => ({
+  verifications: many(verifications),
+}))
+```
+
+## Database Connections
+
+### Development (SQLite)
+
+- **File:** `data/app.db`
+- **Mode:** WAL (Write-Ahead Logging) for performance
+- **Auto-created:** If `DATABASE_URL` not set
+
+```typescript
+// src/server/db/index.ts
+import Database from 'better-sqlite3'
+
+const db = new Database('data/app.db', { readonly: false })
+db.pragma('journal_mode = 'WAL')
+```
+
+### Production (PostgreSQL)
+
+- **Connection Pooling:** 20 connections (configurable)
+- **Environment Variable:** `DATABASE_URL`
+
+```typescript
+// src/server/db/index.ts
+import { drizzle } from 'drizzle-orm/postgres-js'
+import { Pool } from 'postgres'
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 20,
+})
+
+const db = drizzle(pool, { schema })
+```
+
+## Migrations
+
+### Running Migrations
+
+```bash
+# Generate migration files
+npm run db:generate
+
+# Apply migrations
+npm run db:migrate
+
+# Open Drizzle Studio to browse database
+npm run db:studio
+```
+
+### Migration Files
+
+Stored in `drizzle/migrations/` with SQL files:
+
+- `0001_initial_schema.sql`
+- `0002_add_feature.sql` (future migrations)
+
+### SQLite vs PostgreSQL Migrations
+
+The same schema works for both databases. Drizzle handles differences:
+
+- SQLite: `sqlite_table`
+- PostgreSQL: `pg_table`
+
+Some features differ:
+
+- **Auto-increment:** SQLite uses `INTEGER PRIMARY KEY`, PostgreSQL uses `SERIAL`
+- **Text types:** SQLite `TEXT`, PostgreSQL `VARCHAR` or `TEXT`
+- **Boolean:** SQLite `INTEGER (0/1)`, PostgreSQL `BOOLEAN`
+
+## Common Operations
+
+### Query Examples
+
+```typescript
+// Get all users
+const allUsers = await db.select().from(users)
+
+// Get user by email
+const user = await db
+  .select()
+  .from(users)
+  .where(eq(users.email, 'test@example.com'))
+
+// Get user with sessions
+const userWithSessions = await db
+  .select()
+  .from(users)
+  .leftJoin(sessions, eq(users.id, sessions.userId))
+  .where(eq(users.id, userId))
+
+// Insert user
+const newUser = await db
+  .insert(users)
+  .values({
+    name: 'John Doe',
+    email: 'john@example.com',
+  })
+  .returning()
+
+// Update user
+const updatedUser = await db
+  .update(users)
+  .set({ name: 'Jane Doe', updatedAt: new Date() })
+  .where(eq(users.id, userId))
+  .returning()
+
+// Delete user
+await db.delete(users).where(eq(users.id, userId))
+```
+
+### Using tRPC Procedures
+
+```typescript
+// src/server/api/routers/user.ts
+export const userRouter = router({
+  getProfile: protectedProcedure.query(async ({ ctx }) => {
+    return await db.select().from(users).where(eq(users.id, ctx.user.id))
+  }),
+
+  updateProfile: protectedProcedure
+    .input(z.object({ name: z.string() }))
+    .mutation(async ({ ctx, input }) => {
+      const result = await db
+        .update(users)
+        .set({ name: input.name, updatedAt: new Date() })
+        .where(eq(users.id, ctx.user.id))
+        .returning()
+      return result[0]
+    }),
+})
+```
+
+## Performance Optimization
+
+### Indexes
+
+Add indexes for frequently queried columns:
+
+```typescript
+export const users = sqliteTable(
+  'users',
+  {
+    id: text('id').primaryKey(),
+    email: text('email').notNull(),
+  },
+  (table) => ({
+    emailIdx: index('email_idx').on(table.email),
+  })
+)
+```
+
+Recommended indexes:
+
+- `users.email` - For login queries
+- `sessions.userId` - For session lookups
+- `verifications.identifier` - For verification token lookups
+
+### Connection Pooling
+
+PostgreSQL production uses connection pooling:
+
+```typescript
+const pool = new Pool({
+  connectionString: env.DATABASE_URL,
+  max: 20, // Adjust based on traffic
+  idleTimeout: 30000, // 30 seconds
+  connectionTimeoutMillis: 2000, // 2 seconds
+})
+```
+
+### Query Optimization
+
+Tips:
+
+1. **Select specific columns** instead of `*`
+2. **Use `where` clauses** to filter data early
+3. **Limit results** when possible: `.limit(10)`
+4. **Avoid N+1 queries** with proper joins
+
+## Seed Data
+
+The seed script creates sample users and dashboard data:
+
+```bash
+npm run db:seed
+```
+
+Seed data location: `src/server/db/seed.ts`
+
+## Troubleshooting
+
+### Database Locked (SQLite)
+
+**Error:** `Error: database is locked`
+
+**Cause:** WAL file still open from previous dev session
+
+**Solution:**
+
+```bash
+npm run clean
+# This removes WAL files and restarts clean
+```
+
+### Migration Conflicts
+
+**Error:** Migration applies but data is lost
+
+**Cause:** Schema changes incompatible with existing data
+
+**Solution:**
+
+1. Review migration file in `drizzle/migrations/`
+2. Test migration on backup first
+3. Rollback if needed: `npm run db:migrate:down` (if configured)
+
+### Slow Queries
+
+**Detection:**
+
+- Development: Check Drizzle Studio query logs
+- Production: Check database provider dashboard
+
+**Common causes:**
+
+- Missing indexes
+- Unnecessary joins
+- Returning too much data
+
+**Solution:**
+
+1. Add indexes
+2. Optimize query structure
+3. Use pagination for large datasets