AI Context Documentation

# Project Core Overview

## Project Description
A modern SaaS starter template built with Next.js 14, featuring authentication, 
payments, and a complete admin dashboard. Designed for rapid development of 
subscription-based applications.

## Architecture Overview
- **Frontend**: Next.js 14 with App Router
- **Backend**: API Routes with TypeScript
- **Database**: PostgreSQL with Prisma ORM
- **Authentication**: NextAuth.js with multiple providers
- **Payments**: Stripe for subscriptions and one-time payments
- **Styling**: Tailwind CSS with shadcn/ui components

## Key Directories
```
src/
├── app/                 # Next.js app router pages
├── components/          # Reusable UI components
├── lib/                 # Utility functions and configurations
├── types/               # TypeScript type definitions
└── hooks/               # Custom React hooks
```

## Core Concepts

### Feature Flags
The application uses feature flags to enable/disable functionality:
- `FEATURE_PAYMENTS`: Enable Stripe integration
- `FEATURE_ANALYTICS`: Enable analytics tracking
- `FEATURE_ADMIN`: Enable admin dashboard

### Database Schema
Primary entities:
- **User**: Authentication and profile data
- **Subscription**: Payment and billing information
- **Organization**: Multi-tenant support
- **AuditLog**: Activity tracking

## Getting Started
1. Copy `.env.example` to `.env.local`
2. Set up database: `npm run db:setup`
3. Start development: `npm run dev`

## Common Tasks
- Adding new features: See `04-FEATURES.md`
- Database changes: See `02-DATABASE.md`
- Authentication setup: See `01-AUTH.md`

# Authentication System

## Overview
Multi-provider authentication using NextAuth.js with support for email/password,
OAuth providers (Google, GitHub), and magic links.

## Authentication Flow
1. User initiates sign-in
2. Provider validates credentials
3. Session created with JWT
4. User redirected to dashboard

## Providers Configuration
```typescript
// lib/auth.ts
export const authOptions: NextAuthOptions = {
  providers: [
    EmailProvider({
      server: process.env.EMAIL_SERVER,
      from: process.env.EMAIL_FROM,
    }),
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
    GitHubProvider({
      clientId: process.env.GITHUB_ID!,
      clientSecret: process.env.GITHUB_SECRET!,
    }),
  ],
  // ...
}
```

## Session Management
- Sessions stored in database via Prisma adapter
- JWT tokens for stateless authentication
- Automatic session refresh
- Secure logout with token cleanup

## Protected Routes
Use the `useSession` hook or `getServerSession` for protection:

```typescript
// Client-side protection
const { data: session, status } = useSession()
if (status === "loading") return <Loading />
if (!session) return <SignIn />

// Server-side protection
const session = await getServerSession(authOptions)
if (!session) {
  redirect('/auth/signin')
}
```

## User Roles and Permissions
- **user**: Basic authenticated user
- **admin**: Full system access
- **moderator**: Limited admin access

Roles stored in user.role field and checked via middleware.

# AI Context Documentation Index

This directory contains structured documentation designed to help AI assistants 
understand and work with this codebase effectively.

## File Overview

### 📋 Core Documentation
- **00-CORE.md** - Project overview, architecture, and key concepts
- **README.md** - This index file

### 🔐 Authentication & Security  
- **01-AUTH.md** - Authentication system, providers, and session management

### 🗄️ Data & Database
- **02-DATABASE.md** - Database schema, models, and relationships

### 🔌 API & Integration
- **03-API.md** - API endpoints, request/response formats, and integrations

### ⚡ Features & Functionality
- **04-FEATURES.md** - Feature implementations and configuration

## Quick Reference

### Common File Patterns
- Components: `src/components/[category]/ComponentName.tsx`
- Pages: `src/app/[route]/page.tsx`
- API Routes: `src/app/api/[endpoint]/route.ts`
- Types: `src/types/[domain].ts`

### Key Configuration Files
- `next.config.js` - Next.js configuration
- `tailwind.config.ts` - Styling configuration  
- `prisma/schema.prisma` - Database schema
- `.env.local` - Environment variables

### Common Development Tasks
1. **Adding a new page**: Create in `src/app/[route]/page.tsx`
2. **Creating components**: Add to `src/components/[category]/`
3. **Database changes**: Modify `schema.prisma` and run migrations
4. **API endpoints**: Create in `src/app/api/[endpoint]/route.ts`

## AI Assistant Guidelines
When working with this codebase:
1. Always check the relevant context file first
2. Follow existing patterns and conventions
3. Update documentation when making changes
4. Test changes thoroughly before committing