App Development Skill

This skill provides comprehensive knowledge for developing features in the AI Coaching Platform Next.js application.

Purpose

Use this skill when:

• Building new pages and components
• Creating server actions for data operations
• Working with the TanStack Table system
• Understanding the application architecture
• Implementing forms and data validation

Skill Structure

app-development/
├── SKILL.md                # This file - main reference
├── architecture.md         # Application architecture overview
├── component-system.md     # Component patterns and primitives
├── data-flow.md           # Server actions, React Query, data handling
├── tanstack-table.md      # Table component system
└── workflows.md           # Common development workflows

Quick Reference

Tech Stack

• Framework: Next.js 15 with App Router
• UI: React 18, Tailwind CSS
• Database: MongoDB Atlas with Mongoose ODM
• Authentication: Clerk
• State Management: React Query, React Hooks
• Validation: Zod schemas

Key Directories

• src/app/ - Pages and layouts
• src/app/actions/ - Server actions
• src/components/ - Reusable components
• src/hooks/scm/ - SCM React Query hooks (centralized)
• src/lib/schema/mongoose-schema/ - Database models
• src/lib/schema/zod-schema/ - Validation schemas
• src/query/ - React Query providers

Documentation Files

Architecture

@.claude/skills/app-development/architecture.md

• Application structure overview
• File organization patterns
• Key directories and their purposes

Component System

@.claude/skills/app-development/component-system.md

• Component hierarchy (core, composed, domain, features)
• Creating new components
• Styling with Tailwind CSS
• Common component patterns

Data Flow

@.claude/skills/app-development/data-flow.md

• Server action patterns
• React Query usage
• Error handling
• Database operations

TanStack Table

@.claude/skills/app-development/tanstack-table.md

• Table configuration
• Column definitions
• Features (sorting, filtering, pagination)
• Custom cell renderers

Workflows

@.claude/skills/app-development/workflows.md

• Common development tasks
• Step-by-step guides
• Best practices

Database Collections

@.claude/skills/app-development/database-collections.md

• MongoDB collection schemas
• Collection relationships
• Common query patterns

Animation Components

All animation components should be saved in:

src/app/animations/

Available Animations

• DilationAnimation.tsx - Dilation transformation with scale factor slider

Creating New Animations

1. Create component in src/app/animations/
2. Follow SVG-based patterns for math visualizations
3. Include proper TypeScript types
4. Support flexible configuration via props

Code Patterns

Server Action Pattern

"use server";

export async function myAction(input: MyInputType) {
  return withDbConnection(async () => {
    try {
      const validated = MyInputSchema.parse(input);
      const result = await MyModel.findOne({ ... });
      return { success: true, data: result.toJSON() };
    } catch (error) {
      return { success: false, error: handleServerError(error, "Failed") };
    }
  });
}

Component Pattern

"use client";

import React from "react";

interface MyComponentProps {
  // Props with JSDoc comments
}

export function MyComponent({ ...props }: MyComponentProps) {
  return (
    // JSX
  );
}

Key Principles

1. Type Safety - Use proper TypeScript types, avoid any
2. Validation - Use Zod for all external data
3. Server First - Prefer server components and actions
4. React Query - Use for server state management
5. Component Hierarchy - Follow core → composed → domain → features

Integration with Other Skills

• For p5.js animations → Use create-p5-animation skill
• For database operations → See CLAUDE.md for mongosh patterns

---

Last Updated: December 2024