biohazard-vfx/docs/architecture.md

# Biohazard VFX Architecture Document

## Introduction

This document outlines the overall project architecture for Biohazard VFX, including backend systems, shared services, and non-UI specific concerns. Its primary goal is to serve as the guiding architectural blueprint for AI-driven development, ensuring consistency and adherence to chosen patterns and technologies.

**Relationship to Frontend Architecture:**
If the project includes a significant user interface, a separate Frontend Architecture Document will detail the frontend-specific design and MUST be used in conjunction with this document. Core technology stack choices documented herein (see "Tech Stack") are definitive for the entire project, including any frontend components.

### Starter Template or Existing Project

The Biohazard VFX project is built on a Next.js starter template with an established codebase. The architecture builds on the existing foundation with:

- Next.js 15 with App Router as the foundational framework
- Prisma ORM with SQLite for database management
- NextAuth.js for authentication
- Tailwind CSS for styling
- Component-based architecture with reusable elements

The existing project structure provides a solid foundation for the architecture decisions outlined in this document.

### Change Log

| Date | Version | Description | Author |
|------|---------|-------------|---------|
| 2025-09-24 | 1.0 | Initial architecture document | Winston, Architect |

## High Level Architecture

### Technical Summary

The Biohazard VFX system follows a Next.js-based monolithic architecture with a modular component structure. Key components include a content management system, authentication layer, project portfolio, blog engine, and rich media handling. The primary technology choices center around the Next.js ecosystem with Prisma ORM, SQLite database, and Tailwind CSS. The architecture follows modern web application patterns with server-side rendering, client-side interactions, and responsive design. This architecture supports the PRD goals of creating a visually impressive portfolio site for showcasing VFX work.

### High Level Overview

The architecture follows a modular monolith pattern using Next.js with the App Router. The repository follows a monorepo structure with clear separation of concerns. The service architecture is a single Next.js application that handles both static content delivery and dynamic content management through the admin interface. The primary user interaction flow involves visitors browsing the portfolio and blog content, with authenticated users able to access the admin dashboard for content management. Key architectural decisions include using SQLite for simplicity and portability, NextAuth for secure authentication, and Prisma for type-safe database access.

### High Level Project Diagram

```mermaid
graph TB
    subgraph "Biohazard VFX Application"
        A[Next.js App Router]
        B[Pages & Layouts]
        C[API Routes]
        D[Components]
        E[Hooks & Utils]
    end
    
    subgraph "Authentication & Authorization"
        F[NextAuth.js]
        G[Prisma Adapter]
        H[Credentials Provider]
    end
    
    subgraph "Database"
        I[SQLite Database]
        J[Prisma ORM]
    end
    
    subgraph "Content Management"
        K[Admin Dashboard]
        L[Content Forms]
    end
    
    subgraph "External Services"
        M[Image Optimization]
        N[Video Streaming]
    end
    
    A --> B
    A --> C
    A --> D
    A --> E
    
    A --> F
    F --> G
    G --> I
    J --> I
    
    C --> K
    K --> L
    D --> M
    D --> N
    
    I <--> J
    F --> H
```

### Architectural and Design Patterns

- **Modular Monolith:** Using a single Next.js application with clear separation of concerns - _Rationale:_ Balances simplicity for current scale with maintainability and performance optimization through Next.js features
- **Component-Based Architecture:** Reusable and composable UI elements - _Rationale:_ Enables consistent user experience and faster development with maintainable codebase
- **Server-Side Rendering (SSR):** Next.js App Router for SEO and performance - _Rationale:_ Critical for portfolio site to ensure content is indexable and loads quickly
- **API Routes:** Next.js API routes for backend functionality - _Rationale:_ Provides server-side processing without external API service dependencies
- **Repository Pattern:** Prisma ORM abstracting database access - _Rationale:_ Enables type-safe database operations and simplifies data access logic

## Tech Stack

### Cloud Infrastructure

- **Provider:** Self-hosted / Vercel
- **Key Services:** Next.js Runtime, Static Asset Delivery, Serverless Functions
- **Deployment Regions:** Global CDN with edge computing capabilities

### Technology Stack Table

| Category | Technology | Version | Purpose | Rationale |
|----------|------------|---------|---------|-----------|
| **Framework** | Next.js | 15.4.6 | Full-stack React framework | SSR, SSG, API routes, excellent performance and SEO |
| **Language** | TypeScript | 5.9.2 | Primary development language | Strong typing, scalability, maintainability |
| **Runtime** | Node.js | 20.x LTS | JavaScript runtime environment | Compatibility with Next.js and ecosystem |
| **Database** | SQLite | 3.x | Primary database | Lightweight, portable, zero-configuration |
| **ORM** | Prisma | 6.13.0 | Database ORM and migration tool | Type-safe queries, auto-generated client |
| **Authentication** | NextAuth.js | 4.24.11 | Authentication system | Flexible providers, secure sessions |
| **Styling** | Tailwind CSS | 3.4.17 | Utility-first CSS framework | Rapid UI development, consistent styling |
| **UI Components** | Custom Component Library | - | Reusable UI elements | Consistent UX, maintainable interface |
| **Animation** | Framer Motion | 12.23.12 | Animation library | Smooth, performant animations |
| **Icons** | Lucide React, Tabler Icons | 0.542.0, 3.34.1 | Icon components | Lightweight, consistent icon set |
| **Forms** | React Hook Form | 7.62.0 | Form management | Efficient form handling with validation |
| **Validation** | Zod | 4.0.15 | Schema validation | TypeScript integration, runtime validation |
| **Testing** | Vitest, React Testing Library | - | Testing framework | Unit and integration testing |
| **Linting** | ESLint | 9.32.0 | Code linting | Code quality and consistency |
| **Formatting** | Prettier | - | Code formatting | Consistent code style |
| **Package Manager** | npm/yarn | - | Dependency management | Standard Node.js ecosystem tooling |

## Data Models

### User

**Purpose:** Represents authenticated users with roles for access control

**Key Attributes:**
- id: String - Unique identifier for the user
- email: String - User's email address, unique
- name: String - User's display name
- password: String - Hashed password
- role: Role - User's permission level (ADMIN, EDITOR)
- avatar: String? - Optional profile image URL
- createdAt: DateTime - Account creation timestamp
- updatedAt: DateTime - Last modification timestamp

**Relationships:**
- One-to-many with BlogPost (author)
- One-to-many with Account (user accounts)
- One-to-many with Session (user sessions)

### Project

**Purpose:** Represents portfolio items with before/after VFX work

**Key Attributes:**
- id: String - Unique identifier for the project
- title: String - Project title
- description: String? - Detailed description of the project
- thumbnail: String - URL to thumbnail image
- size: Size - Project size classification (BIG, SMALL)
- embed: String? - Embedded media URL
- video: String? - Project video URL
- credits: String - Project credits information
- info: String - Additional project information
- category: String? - Project category
- tags: String? - Comma-separated tags
- featured: Boolean - Whether project is featured
- published: Boolean - Whether project is published
- publishedAt: DateTime? - Publishing timestamp
- createdAt: DateTime - Creation timestamp
- updatedAt: DateTime - Last modification timestamp

**Relationships:**
- No direct relationships with other models

### BlogPost

**Purpose:** Represents blog articles published on the platform

**Key Attributes:**
- id: String - Unique identifier for the blog post
- title: String - Blog post title
- slug: String - URL-friendly identifier, unique
- content: String - Blog post content in markdown
- excerpt: String? - Brief summary of the post
- featuredImage: String? - URL to featured image
- category: String? - Blog category
- tags: String? - Comma-separated tags
- published: Boolean - Whether post is published
- publishedAt: DateTime? - Publishing timestamp
- authorId: String - Reference to author user
- createdAt: DateTime - Creation timestamp
- updatedAt: DateTime - Last modification timestamp

**Relationships:**
- Many-to-one with User (author)

### TeamMember

**Purpose:** Represents team members in the VFX studio

**Key Attributes:**
- id: String - Unique identifier for the team member
- name: String - Team member's name
- title: String - Professional title
- quote: String? - Personal quote or bio
- image: String - URL to team member image
- instagram: String? - Instagram handle
- order: Int - Display order
- createdAt: DateTime - Creation timestamp
- updatedAt: DateTime - Last modification timestamp

**Relationships:**
- No direct relationships with other models

### FAQ

**Purpose:** Frequently asked questions for the website visitors

**Key Attributes:**
- id: String - Unique identifier for the FAQ
- question: String - The question text
- answer: String - The answer text
- order: Int - Display order
- published: Boolean - Whether FAQ is published
- createdAt: DateTime - Creation timestamp
- updatedAt: DateTime - Last modification timestamp

**Relationships:**
- No direct relationships with other models

### SiteAsset

**Purpose:** Site-wide media assets controllable from admin

**Key Attributes:**
- id: String - Unique identifier for the asset
- key: String - Unique key for referencing (e.g. "home.hero.image")
- label: String - Human-readable name
- type: AssetType - Type of asset (IMAGE, VIDEO)
- url: String - Asset URL
- alt: String? - Alt text for accessibility
- createdAt: DateTime - Creation timestamp
- updatedAt: DateTime - Last modification timestamp

**Relationships:**
- No direct relationships with other models

## Components

### App Component

**Responsibility:** Entry point for the Next.js application with layout and routing management

**Key Interfaces:**
- Root layout with metadata
- Global styling and font loading
- Page routing through App Router

**Dependencies:** Next.js, Providers, Navigation, Footer

**Technology Stack:** Next.js App Router, React, Tailwind CSS

### Providers Component

**Responsibility:** Manages application-wide providers and contexts

**Key Interfaces:**
- SessionProvider for authentication state
- ThemeProvider for dark/light mode
- MotionConfig for animations
- LoadingProvider for loading states
- Toaster for notifications

**Dependencies:** NextAuth.js, next-themes, framer-motion, custom providers

**Technology Stack:** React Context API, NextAuth.js, framer-motion

### Authentication Layer

**Responsibility:** Handles user authentication and authorization

**Key Interfaces:**
- API routes for NextAuth
- Session management
- Role-based access control

**Dependencies:** NextAuth.js, Prisma, bcrypt

**Technology Stack:** NextAuth.js, Prisma ORM, bcryptjs

### Content Management System

**Responsibility:** Admin dashboard for managing all content types

**Key Interfaces:**
- Project management interface
- Blog post editor
- Team member management
- FAQ editor
- Site asset management

**Dependencies:** Prisma, React Hook Form, Zod

**Technology Stack:** Next.js API routes, Prisma ORM, React Hook Form, Zod

### UI Components Library

**Responsibility:** Reusable UI elements across the application

**Key Interfaces:**
- Button components with various styles
- Card components for content display
- Form components with validation
- Motion components for animations
- Custom UI elements like the Compare component

**Dependencies:** Tailwind CSS, framer-motion, lucide-react, tabler-icons-react

**Technology Stack:** React, Tailwind CSS, framer-motion

### Component Diagrams

```mermaid
graph TB
    subgraph "UI Layer"
        A[Navigation] --> B[Layout Components]
        C[Footer] --> B
        D[Header] --> B
        E[Page Components] --> B
        F[UI Components] --> E
    end
    
    subgraph "Logic Layer"
        G[Providers]
        H[Authentication]
        I[Content Management]
        J[Data Fetching]
    end
    
    subgraph "Data Layer"
        K[Prisma Client]
        L[SQLite Database]
        M[API Routes]
    end
    
    B --> G
    E --> G
    G --> H
    G --> I
    I --> K
    J --> K
    M --> K
    K --> L
    H --> K
```

## External APIs

### Database API

**Purpose:** Prisma ORM for database operations

**Documentation:** https://www.prisma.io/docs

**Base URL(s):** Local connection to SQLite file

**Authentication:** Direct file access, no authentication required

**Rate Limits:** N/A

**Key Endpoints Used:**
- `model.findUnique()` - Retrieve specific records
- `model.findMany()` - Retrieve multiple records
- `model.create()` - Create new records
- `model.update()` - Update existing records
- `model.delete()` - Delete records

**Integration Notes:** Type-safe database access through Prisma schema, connection pooling handled automatically

### NextAuth API

**Purpose:** Authentication and session management

**Documentation:** https://next-auth.js.org/getting-started/introduction

**Base URL(s):** /api/auth/[...nextauth]

**Authentication:** Credentials provider with email/password

**Rate Limits:** N/A

**Key Endpoints Used:**
- `POST /api/auth/signin` - Sign in endpoint
- `POST /api/auth/signout` - Sign out endpoint
- `GET /api/auth/session` - Get current session
- `GET /api/auth/csrf` - Get CSRF token

**Integration Notes:** Session tokens stored in secure, HTTP-only cookies

## Core Workflows

```mermaid
sequenceDiagram
    participant U as User
    participant N as Next.js App
    participant A as Authentication
    participant P as Prisma
    participant D as Database
    
    U->>N: Visit website
    N->>P: Fetch public content
    P->>D: Query projects/blog posts
    D->>P: Return data
    P->>N: Processed data
    N->>U: Render page
    
    U->>N: Navigate to admin login
    N->>U: Show login form
    U->>A: Submit credentials
    A->>P: Verify user
    P->>D: Check user credentials
    D->>P: Return user data
    P->>A: User verified
    A->>U: Issue session token
    U->>N: Access admin dashboard
    N->>P: Fetch admin data
    P->>D: Query admin content
    D->>P: Return admin data
    P->>N: Processed admin data
    N->>U: Render admin interface
```

## Database Schema

```sql
-- Users table for authentication
CREATE TABLE users (
  id TEXT PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  password TEXT NOT NULL,
  role TEXT DEFAULT 'ADMIN',
  avatar TEXT,
  createdAt DATETIME DEFAULT CURRENT_TIMESTAMP,
  updatedAt DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Projects table for portfolio items
CREATE TABLE projects (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  description TEXT,
  thumbnail TEXT NOT NULL,
  size TEXT DEFAULT 'SMALL',
  embed TEXT,
  video TEXT,
  credits TEXT NOT NULL,
  info TEXT NOT NULL,
  category TEXT,
  tags TEXT,
  featured BOOLEAN DEFAULT 0,
  published BOOLEAN DEFAULT 1,
  publishedAt DATETIME,
  createdAt DATETIME DEFAULT CURRENT_TIMESTAMP,
  updatedAt DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Blog posts table
CREATE TABLE blog_posts (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  slug TEXT UNIQUE NOT NULL,
  content TEXT NOT NULL,
  excerpt TEXT,
  featuredImage TEXT,
  category TEXT,
  tags TEXT,
  published BOOLEAN DEFAULT 0,
  publishedAt DATETIME,
  authorId TEXT NOT NULL,
  createdAt DATETIME DEFAULT CURRENT_TIMESTAMP,
  updatedAt DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (authorId) REFERENCES users(id)
);

-- Team members table
CREATE TABLE team_members (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  title TEXT NOT NULL,
  quote TEXT,
  image TEXT NOT NULL,
  instagram TEXT,
  order INTEGER DEFAULT 0,
  createdAt DATETIME DEFAULT CURRENT_TIMESTAMP,
  updatedAt DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- FAQs table
CREATE TABLE faqs (
  id TEXT PRIMARY KEY,
  question TEXT NOT NULL,
  answer TEXT NOT NULL,
  order INTEGER DEFAULT 0,
  published BOOLEAN DEFAULT 1,
  createdAt DATETIME DEFAULT CURRENT_TIMESTAMP,
  updatedAt DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Site assets table
CREATE TABLE site_assets (
  id TEXT PRIMARY KEY,
  key TEXT UNIQUE NOT NULL,
  label TEXT NOT NULL,
  type TEXT NOT NULL,
  url TEXT NOT NULL,
  alt TEXT,
  createdAt DATETIME DEFAULT CURRENT_TIMESTAMP,
  updatedAt DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- NextAuth required tables
CREATE TABLE accounts (
  id TEXT PRIMARY KEY,
  userId TEXT NOT NULL,
  type TEXT NOT NULL,
  provider TEXT NOT NULL,
  providerAccountId TEXT NOT NULL,
  refresh_token TEXT,
  access_token TEXT,
  expires_at INTEGER,
  token_type TEXT,
  scope TEXT,
  id_token TEXT,
  session_state TEXT,
  FOREIGN KEY (userId) REFERENCES users(id) ON DELETE CASCADE,
  UNIQUE (provider, providerAccountId)
);

CREATE TABLE sessions (
  id TEXT PRIMARY KEY,
  sessionToken TEXT UNIQUE NOT NULL,
  userId TEXT NOT NULL,
  expires DATETIME NOT NULL,
  FOREIGN KEY (userId) REFERENCES users(id) ON DELETE CASCADE
);

CREATE TABLE verification_tokens (
  identifier TEXT NOT NULL,
  token TEXT UNIQUE NOT NULL,
  expires DATETIME NOT NULL,
  UNIQUE (identifier, token)
);

-- Indexes for performance
CREATE INDEX idx_projects_featured ON projects(featured, published);
CREATE INDEX idx_projects_category ON projects(category);
CREATE INDEX idx_blog_posts_published ON blog_posts(published, publishedAt);
CREATE INDEX idx_blog_posts_author ON blog_posts(authorId);
CREATE INDEX idx_faqs_published ON faqs(published);
```

## Source Tree

```
biohazard-vfx-nextjs/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── admin/              # Admin dashboard pages
│   │   │   ├── page.tsx        # Admin dashboard
│   │   │   ├── projects/       # Project management
│   │   │   ├── blog/           # Blog management
│   │   │   ├── team/           # Team management
│   │   │   ├── faq/            # FAQ management
│   │   │   └── media/          # Media management
│   │   ├── api/                # API routes
│   │   │   └── auth/
│   │   │       └── [...nextauth]/
│   │   │           └── route.ts # NextAuth API route
│   │   ├── projects/           # Public project pages
│   │   ├── blog/               # Public blog pages
│   │   ├── globals.css         # Global styles
│   │   ├── layout.tsx          # Root layout
│   │   ├── page.tsx            # Home page
│   │   └── ...                 # Other public pages
│   ├── components/             # Reusable UI components
│   │   ├── admin/              # Admin-specific components
│   │   ├── motion/             # Animation components
│   │   ├── ui/                 # Base UI components
│   │   ├── Buttons.tsx         # Button components
│   │   ├── Cards.tsx           # Card components
│   │   ├── Forms.tsx           # Form components
│   │   ├── Navigation.tsx      # Navigation components
│   │   └── ...                 # Other components
│   ├── fonts/                  # Custom font files
│   ├── hooks/                  # Custom React hooks
│   ├── lib/                    # Shared utilities
│   │   ├── auth.ts             # Authentication utilities
│   │   ├── prisma.ts           # Prisma client
│   │   ├── metadata.ts         # Metadata utilities
│   │   └── utils.ts            # General utilities
│   ├── pages_legacy_backup/    # Legacy pages router backup
│   ├── types/                  # TypeScript type definitions
│   ├── public/                 # Static assets
│   │   ├── images/             # Image assets
│   │   ├── videos/             # Video assets
│   │   └── ...                 # Other static files
│   ├── instrumentation.ts      # Sentry instrumentation
│   └── instrumentation-client.ts # Client instrumentation
├── prisma/                     # Prisma configuration
│   ├── schema.prisma           # Database schema
│   ├── seed.ts                 # Database seed script
│   └── migrate-static-content.ts # Migration script
├── docs/                       # Documentation
│   └── architecture.md         # This document
├── .env.example                # Environment variables example
├── .env.local                  # Local environment variables
├── next.config.js              # Next.js configuration
├── tailwind.config.js          # Tailwind CSS configuration
├── tsconfig.json               # TypeScript configuration
├── package.json                # Project dependencies
└── README.md                   # Project documentation
```

## Infrastructure and Deployment

### Infrastructure as Code

- **Tool:** Vercel Platform as a Service
- **Location:** `vercel.json`
- **Approach:** Configuration-based deployment with automatic environment detection

### Deployment Strategy

- **Strategy:** Git-based continuous deployment
- **CI/CD Platform:** Vercel's built-in CI/CD
- **Pipeline Configuration:** `vercel.json` and GitHub integration

### Environments

- **Development:** Local development environment - Node.js 20.x with hot reloading
- **Preview:** Branch-based preview deployments - Auto-generated for pull requests
- **Production:** Main branch deployment - Live production site with CDN distribution

### Environment Promotion Flow

```
Feature Branch → Pull Request → Preview Deployment → Merge to Main → Production Deploy
```

### Rollback Strategy

- **Primary Method:** Version-based rollback through Vercel dashboard
- **Trigger Conditions:** Critical errors detected in production
- **Recovery Time Objective:** 5-10 minutes for rollback execution

## Error Handling Strategy

### General Approach

- **Error Model:** Next.js error boundaries and try-catch patterns
- **Exception Hierarchy:** Custom error classes extending base Error
- **Error Propagation:** Proper error bubbling with meaningful messages

### Logging Standards

- **Library:** Built-in Next.js logging plus Sentry for error tracking
- **Format:** Structured JSON logs with timestamp, level, message, and context
- **Levels:** info, warn, error, debug
- **Required Context:**
  - Correlation ID: UUID per request chain
  - Service Context: Current page/API route
  - User Context: Non-sensitive user information only

### Error Handling Patterns

#### External API Errors

- **Retry Policy:** Exponential backoff with 3 attempts
- **Circuit Breaker:** Not implemented (not needed for current architecture)
- **Timeout Configuration:** 10s for API calls, 30s for file uploads
- **Error Translation:** Generic error messages for user-facing errors

#### Business Logic Errors

- **Custom Exceptions:** ValidationError, AuthorizationError, ResourceNotFoundError
- **User-Facing Errors:** Human-readable messages via toast notifications
- **Error Codes:** Standardized error codes for API responses

#### Data Consistency

- **Transaction Strategy:** Prisma transactions for multi-step operations
- **Compensation Logic:** Not applicable for current use cases
- **Idempotency:** Not required for current architecture

## Coding Standards

### Core Standards

- **Languages & Runtimes:** TypeScript 5.9.2, Node.js 20.x LTS
- **Style & Linting:** ESLint with Next.js recommended rules, Prettier for formatting
- **Test Organization:** Co-located tests with component files (Component.test.tsx)

### Critical Rules

- **Never use console.log in production code** - use proper logging
- **All database queries must use Prisma client** - no direct SQL
- **API responses must follow Next.js patterns** - no custom response formats
- **All external inputs must be validated** - use Zod schemas
- **Authentication checks required** - use session validation middleware
- **Image optimization mandatory** - use Next.js Image component
- **Accessibility compliance** - follow WCAG 2.1 AA guidelines

### Language-Specific Guidelines

#### TypeScript Specifics

- **Strict Mode:** Enable strict TypeScript compiler options
- **Type Safety:** Prefer types over interfaces for internal types
- **Null Handling:** Use optional chaining and nullish coalescing
- **Async/Await:** Always handle promise rejections appropriately

## Test Strategy and Standards

### Testing Philosophy

- **Approach:** Test-driven development for critical business logic, test-after for UI components
- **Coverage Goals:** 80% line coverage for business logic, 70% for UI components
- **Test Pyramid:** 70% unit tests, 20% integration tests, 10% end-to-end tests

### Test Types and Organization

#### Unit Tests

- **Framework:** Vitest
- **File Convention:** ComponentName.test.tsx, utilName.test.ts
- **Location:** Co-located with source files
- **Mocking Library:** Vitest built-in mocking
- **Coverage Requirement:** All public functions and methods

**AI Agent Requirements:**
- Generate tests for all public methods
- Cover edge cases and error conditions
- Follow AAA pattern (Arrange, Act, Assert)
- Mock all external dependencies

#### Integration Tests

- **Scope:** API routes, database operations, authentication flows
- **Location:** `__tests__/integration/`
- **Test Infrastructure:**
  - **Database:** In-memory SQLite for tests
  - **Authentication:** Mock sessions

#### End-to-End Tests

- **Framework:** Playwright
- **Scope:** Critical user journeys (login, content creation)
- **Environment:** Preview deployment or local
- **Test Data:** Seed specific test data

### Test Data Management

- **Strategy:** Test factories with Prisma seed
- **Fixtures:** Located in `__tests__/fixtures/`
- **Factories:** Factory pattern for test data creation
- **Cleanup:** After each test run, reset database state

### Continuous Testing

- **CI Integration:** Run tests on each push and PR
- **Performance Tests:** Not currently implemented
- **Security Tests:** Dependency scanning with npm audit

## Security

### Input Validation

- **Validation Library:** Zod
- **Validation Location:** API routes and form submissions
- **Required Rules:**
  - All external inputs MUST be validated
  - Validation at API boundary before processing
  - Whitelist approach preferred over blacklist

### Authentication & Authorization

- **Auth Method:** NextAuth.js with credentials provider
- **Session Management:** JWT in secure, HTTP-only cookies
- **Required Patterns:**
  - Server-side authentication check for protected routes
  - Role-based access control for admin features

### Secrets Management

- **Development:** Environment variables in .env.local
- **Production:** Vercel environment variables
- **Code Requirements:**
  - NEVER hardcode secrets
  - Access via environment variables only
  - No secrets in logs or error messages

### API Security

- **Rate Limiting:** Basic rate limiting via middleware
- **CORS Policy:** Restrictive CORS policy
- **Security Headers:** Next.js default headers plus additional security headers
- **HTTPS Enforcement:** Automatic on production deployment

### Data Protection

- **Encryption at Rest:** Provided by hosting platform
- **Encryption in Transit:** HTTPS required for all connections
- **PII Handling:** Minimize collection and storage of personal information
- **Logging Restrictions:** No sensitive data in logs

### Dependency Security

- **Scanning Tool:** npm audit, GitHub dependabot
- **Update Policy:** Weekly dependency updates
- **Approval Process:** Review for security vulnerabilities

### Security Testing

- **SAST Tool:** GitHub code scanning
- **DAST Tool:** Not currently implemented
- **Penetration Testing:** Periodic manual testing

## Checklist Results Report

The architecture document has been reviewed against the architect checklist standards and confirmed to include all required sections with appropriate detail for AI-driven development.

## Next Steps

After completing the architecture:

1. If project has UI components:
   - Use "Frontend Architecture Mode"
   - Provide this document as input

2. For all projects:
   - Review with Product Owner
   - Begin story implementation with Dev agent
   - Set up infrastructure with DevOps agent

3. Include specific prompts for next agents if needed

### Architect Prompt

Create a detailed frontend architecture document that builds upon the backend architecture established in this document. Focus on the component design system, UI patterns, responsive design approach, and user experience flows that complement the Next.js foundation and content management system defined here.