ros/agentic-coding-starter-kit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor/ migrate from OpenAI to OpenRouter integration

Browse Source 
Major improvements to AI integration and developer experience:

## OpenRouter Migration
- Replaced @ai-sdk/openai with @openrouter/ai-sdk-provider
- Updated chat API route to use OpenRouter for access to 100+ AI models
- Changed environment variables from OPENAI_* to OPENROUTER_*
- Updated default model from gpt-5-mini to openai/gpt-5-mini
- Benefits: Users can now access multiple AI providers (OpenAI, Anthropic, etc.) through a single unified API

## Documentation Overhaul
- Expanded CLAUDE.md from 3 lines to comprehensive 225-line guide
- Added complete project structure, tech stack overview, and AI integration guidelines
- Documented all environment variables, scripts, and common tasks
- Added critical rules for AI assistants working with the codebase
- Enhanced checkpoint command with detailed step-by-step instructions

## README Updates
- Updated feature list to highlight OpenRouter integration
- Revised setup instructions for OpenRouter API key acquisition
- Updated environment variable examples and deployment configuration
- Changed all OpenAI references to OpenRouter throughout documentation

## Create Command Updates
- Bumped create-agentic-app version from 1.0.0 to 1.0.1
- Synchronized all template files with main project documentation
- Updated template env.example and package.json with OpenRouter configuration

## Dependency Updates
- Added @openrouter/ai-sdk-provider@^1.2.0
- Updated @ai-sdk/openai from ^2.0.53 to ^2.0.60
- Updated @ai-sdk/react from ^2.0.78 to ^2.0.86
- Updated ai from ^5.0.78 to ^5.0.86
- Updated better-auth from ^1.3.29 to ^1.3.34
- Updated drizzle-kit from ^0.31.5 to ^0.31.6
- Updated eslint from ^9.38.0 to ^9.39.0
- Various type definition updates

Breaking Changes:
- Projects must update environment variables from OPENAI_* to OPENROUTER_*
- API keys must be obtained from openrouter.ai instead of platform.openai.com
- Model names now follow OpenRouter format (e.g., "openai/gpt-5-mini")

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Leon van Zyl
2025-11-03 14:49:40 +02:00
parent 9ca00bec8f
commit 61e98f23cf
13 changed files with 878 additions and 377 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
CLAUDE.md
View File

@@ -1,3 +1,225 @@
- Always run the LINT and TYPESCHECK scripts after completing your changes. This is to check for any issues.
- NEVER start the dev server yourself. If you need something from the terminal, ask the user to provide it to you.
- Avoid using custom colors unless very specifically instructed to do so. Stick to standard tailwind and shadcn colors, styles and tokens.
# Agentic Coding Boilerplate - AI Assistant Guidelines
## Project Overview
This is a Next.js 15 boilerplate for building AI-powered applications with authentication, database, and modern UI components.
### Tech Stack
- **Framework**: Next.js 15 with App Router, React 19, TypeScript
- **AI Integration**: Vercel AI SDK 5 + OpenRouter (access to 100+ AI models)
- **Authentication**: BetterAuth with Google OAuth
- **Database**: PostgreSQL with Drizzle ORM
- **UI**: shadcn/ui components with Tailwind CSS 4
- **Styling**: Tailwind CSS with dark mode support (next-themes)
## AI Integration with OpenRouter
### Key Points
- This project uses **OpenRouter** as the AI provider, NOT direct OpenAI
- OpenRouter provides access to 100+ AI models through a single unified API
- Default model: `openai/gpt-5-mini` (configurable via `OPENROUTER_MODEL` env var)
- Users browse models at: https://openrouter.ai/models
- Users get API keys from: https://openrouter.ai/settings/keys
### AI Implementation Files
- `src/app/api/chat/route.ts` - Chat API endpoint using OpenRouter
- Package: `@openrouter/ai-sdk-provider` (not `@ai-sdk/openai`)
- Import: `import { openrouter } from "@openrouter/ai-sdk-provider"`
## Project Structure
```
src/
├── app/ # Next.js App Router
│ ├── api/
│ │ ├── auth/[...all]/ # Better Auth catch-all route
│ │ ├── chat/route.ts # AI chat endpoint (OpenRouter)
│ │ └── diagnostics/ # System diagnostics
│ ├── chat/page.tsx # AI chat interface (protected)
│ ├── dashboard/page.tsx # User dashboard (protected)
│ ├── profile/page.tsx # User profile (protected)
│ ├── page.tsx # Home/landing page
│ └── layout.tsx # Root layout
├── components/
│ ├── auth/ # Authentication components
│ │ ├── sign-in-button.tsx
│ │ ├── sign-out-button.tsx
│ │ └── user-profile.tsx
│ ├── ui/ # shadcn/ui components
│ │ ├── button.tsx
│ │ ├── card.tsx
│ │ ├── dialog.tsx
│ │ ├── dropdown-menu.tsx
│ │ ├── avatar.tsx
│ │ ├── badge.tsx
│ │ ├── separator.tsx
│ │ ├── mode-toggle.tsx # Dark/light mode toggle
│ │ └── github-stars.tsx
│ ├── site-header.tsx # Main navigation header
│ ├── site-footer.tsx # Footer component
│ ├── theme-provider.tsx # Dark mode provider
│ ├── setup-checklist.tsx # Setup guide component
│ └── starter-prompt-modal.tsx # Starter prompts modal
└── lib/
├── auth.ts # Better Auth server config
├── auth-client.ts # Better Auth client hooks
├── db.ts # Database connection
├── schema.ts # Drizzle schema (users, sessions, etc.)
└── utils.ts # Utility functions (cn, etc.)
```
## Environment Variables
Required environment variables (see `env.example`):
```env
# Database
POSTGRES_URL=postgresql://user:password@localhost:5432/db_name
# Better Auth
BETTER_AUTH_SECRET=32-char-random-string
# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
# AI via OpenRouter
OPENROUTER_API_KEY=sk-or-v1-your-key
OPENROUTER_MODEL=openai/gpt-5-mini # or any model from openrouter.ai/models
# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
```
## Available Scripts
```bash
npm run dev # Start dev server (DON'T run this yourself - ask user)
npm run build # Build for production (runs db:migrate first)
npm run start # Start production server
npm run lint # Run ESLint (ALWAYS run after changes)
npm run typecheck # TypeScript type checking (ALWAYS run after changes)
npm run db:generate # Generate database migrations
npm run db:migrate # Run database migrations
npm run db:push # Push schema changes to database
npm run db:studio # Open Drizzle Studio (database GUI)
npm run db:dev # Push schema for development
npm run db:reset # Reset database (drop all tables)
```
## Documentation Files
The project includes technical documentation in `docs/`:
- `docs/technical/ai/streaming.md` - AI streaming implementation guide
- `docs/technical/ai/structured-data.md` - Structured data extraction
- `docs/technical/react-markdown.md` - Markdown rendering guide
- `docs/technical/betterauth/polar.md` - Polar payment integration
- `docs/business/starter-prompt.md` - Business context for AI prompts
## Guidelines for AI Assistants
### CRITICAL RULES
1. **ALWAYS run lint and typecheck** after completing changes:
```bash
npm run lint && npm run typecheck
```
2. **NEVER start the dev server yourself**
- If you need dev server output, ask the user to provide it
- Don't run `npm run dev` or `pnpm dev`
3. **Use OpenRouter, NOT OpenAI directly**
- Import from `@openrouter/ai-sdk-provider`
- Use `openrouter()` function, not `openai()`
- Model names follow OpenRouter format: `provider/model-name`
4. **Styling Guidelines**
- Stick to standard Tailwind CSS utility classes
- Use shadcn/ui color tokens (e.g., `bg-background`, `text-foreground`)
- Avoid custom colors unless explicitly requested
- Support dark mode with appropriate Tailwind classes
5. **Authentication**
- Server-side: Import from `@/lib/auth` (Better Auth instance)
- Client-side: Import hooks from `@/lib/auth-client`
- Protected routes should check session in Server Components
- Use existing auth components from `src/components/auth/`
6. **Database Operations**
- Use Drizzle ORM (imported from `@/lib/db`)
- Schema is defined in `@/lib/schema`
- Always run migrations after schema changes
- PostgreSQL is the database (not SQLite, MySQL, etc.)
7. **Component Creation**
- Use existing shadcn/ui components when possible
- Follow the established patterns in `src/components/ui/`
- Support both light and dark modes
- Use TypeScript with proper types
8. **API Routes**
- Follow Next.js 15 App Router conventions
- Use Route Handlers (route.ts files)
- Return Response objects
- Handle errors appropriately
### Best Practices
- Read existing code patterns before creating new features
- Maintain consistency with established file structure
- Use the documentation files when implementing related features
- Test changes with lint and typecheck before considering complete
- When modifying AI functionality, refer to `docs/technical/ai/` guides
### Common Tasks
**Adding a new page:**
1. Create in `src/app/[route]/page.tsx`
2. Use Server Components by default
3. Add to navigation if needed
**Adding a new API route:**
1. Create in `src/app/api/[route]/route.ts`
2. Export HTTP method handlers (GET, POST, etc.)
3. Use proper TypeScript types
**Adding authentication to a page:**
1. Import auth instance: `import { auth } from "@/lib/auth"`
2. Get session: `const session = await auth.api.getSession({ headers: await headers() })`
3. Check session and redirect if needed
**Working with the database:**
1. Update schema in `src/lib/schema.ts`
2. Generate migration: `npm run db:generate`
3. Apply migration: `npm run db:migrate`
4. Import `db` from `@/lib/db` to query
**Modifying AI chat:**
1. Backend: `src/app/api/chat/route.ts`
2. Frontend: `src/app/chat/page.tsx`
3. Reference streaming docs: `docs/technical/ai/streaming.md`
4. Remember to use OpenRouter, not direct OpenAI
## Package Manager
This project uses **pnpm** (see `pnpm-lock.yaml`). When running commands:
- Use `pnpm` instead of `npm` when possible
- Scripts defined in package.json work with `pnpm run [script]`