update architecture docs

CLAUDE.md

···
 4. Test with `bun run dev`
 5. See `packages/client/CLAUDE.md` for patterns
 
-### Type Sharing Between Packages
+### Path Aliases
 
-If you need to share types from server to client:
-1. Add workspace dependency in `packages/client/package.json`:
-   ```json
-   "dependencies": {
-     "@watproto/server": "workspace:*"
-   }
-   ```
-2. Import types (not runtime code):
-   ```typescript
-   import type { Account } from '@watproto/server/src/db/schema'
-   ```
+The monorepo uses TypeScript path aliases for cleaner imports:
+
+**Configured in `tsconfig.root.json`:**
+- `@api/*` → `packages/server/src/*` - Server internal imports
+- `@www/*` → `packages/client/app/*` - Client internal imports
+
+**Server Usage** (`packages/server`):
+```typescript
+import { db } from '@api/db/db'
+import env from '@api/lib/env'
+import { createOrUpdateAccount } from '@api/lib/account'
+```
+
+**Client Usage** (`packages/client`):
+```typescript
+// Client internal imports
+import { Header } from '@www/components/Header'
+import { apiClient } from '@www/lib/api'
+
+// Import server types (type-only imports)
+import type { app } from '@api/index'
+import type { Account } from '@api/db/schema'
+```
+
+**Benefits:**
+- Clean, consistent import paths across the monorepo
+- No relative path traversal (`../../..`)
+- Type sharing between packages without workspace dependencies
+- Vite and Bun automatically resolve these paths
+
+**Note:** Only import types from server to client, never runtime code.
 
 ## Future Expansion
 

packages/client/CLAUDE.md

···
 }
 ```
 
-**Type Sharing** (when needed):
-- Can import types from server package via workspace dependencies
-- Add to dependencies: `"@watproto/server": "workspace:*"`
-- Import: `import type { AccountType } from '@watproto/server/src/db/schema'`
+**Type Sharing with Server:**
+The client can import server types using the `@api/*` path alias:
+
+```typescript
+// Import server types (type-only imports)
+import type { app } from '@api/index'      // For Eden Treaty type-safe API client
+import type { Account } from '@api/db/schema'  // Database types
+import type { SessionData } from '@api/lib/session'  // Session types
+
+// Use in your code
+const apiClient = treaty<typeof app>(API_URL)  // Type-safe API client
+```
+
+**Important:** Only import types from server (`import type`), never runtime code
 
 ### Styling
 
···
 - Access via `import.meta.env.VITE_*`
 - Never commit `.env.local` to git
 
-### TypeScript Configuration
-- Path aliases configured in `tsconfig.json`
-- Vite handles path resolution via `vite-tsconfig-paths` plugin
+### Path Aliases
+
+The client uses path aliases for clean imports:
+
+**Configuration** (in root `tsconfig.root.json`):
+- `@www/*` → `packages/client/app/*` - Client internal imports
+- `@api/*` → `packages/server/src/*` - Server type imports
+
+**Usage Examples:**
+```typescript
+// Client internal imports
+import { Header } from '@www/components/Header'
+import { UserMenu } from '@www/components/UserMenu'
+import { apiClient } from '@www/lib/api'
+import { env } from '@www/lib/env'
+
+// Server type imports (type-only)
+import type { app } from '@api/index'
+import type { Account } from '@api/db/schema'
+```
+
+**Benefits:**
+- Clean, consistent import paths
+- No relative path traversal (`../../../components/Header`)
+- Type-safe API calls using server types
+- Better refactoring support
+
+**Vite Configuration:**
+- Uses `vite-tsconfig-paths` plugin to resolve aliases
+- Automatically picks up paths from root `tsconfig.root.json`
+
+**TypeScript:**
 - Type generation via `react-router typegen` command
+- Strict mode enabled for better type safety
 
 ### Build & Deployment
 - Production build outputs to `build/` directory

packages/server/CLAUDE.md

···
 ## Key Implementation Details
 
 ### Path Aliases
-- Use `@/*` imports for `src/*` files (configured in tsconfig.json)
-- Use `@/../*` for parent directory access (e.g., `@/../jwks.json`)
+
+The server uses the `@api/*` path alias for clean internal imports:
+
+**Configuration** (in root `tsconfig.root.json`):
+- `@api/*` → `packages/server/src/*`
+
+**Usage Examples:**
+```typescript
+import { db } from '@api/db/db'
+import env from '@api/lib/env'
+import { createOrUpdateAccount } from '@api/lib/account'
+import { type Account } from '@api/db/schema'
+import keys from '@api/../jwks.json'  // Parent directory access
+```
+
+**Benefits:**
+- Consistent import paths regardless of file depth
+- No relative path hell (`../../../lib/env`)
+- Better refactoring support
+- Shared with client for type imports
+
+**Note:** Use `@api/../*` for accessing files in the package root (e.g., `jwks.json`)
 
 ### OAuth Security
 - Cookies are httpOnly, secure, sameSite=lax