Fullstack Feature

Orchestrates the creation of a complete feature across backend and frontend.

Overview

A fullstack feature typically requires:

1. Backend API module (Clean Architecture)
2. Database migration
3. Frontend API types generation
4. Frontend hooks
5. Frontend page and components

Workflow

Phase 1: Backend

Step 1: Create API Module

Use the

create-api-module

skill or scaffold script:

python .claude/skills/create-api-module/scripts/scaffold_module.py {feature_name}

This creates:

• back/src/api/{feature}/

  with Clean Architecture structure

• back/tests/api/{feature}/

  with test files

Step 2: Customize the Module

1. Update models in

   infrastructure/models.py

2. Add repository methods in

   infrastructure/repository.py

3. Implement business logic in

   domain/

4. Create API endpoints in

   api/router.py

5. Register router in

   back/src/api/routes.py

Step 3: Create Database Migration

docker compose exec back uv run alembic revision --autogenerate -m "Add {feature} table"

Step 4: Run Backend Tests

cd back && task tests

Phase 2: Frontend

Step 5: Generate API Types

Ensure backend is running, then:

cd front && pnpm run generate:api

Step 6: Create Feature Hook

Create

front/lib/hooks/use-{feature}.ts

:

• Query key factory

• use{Feature}Suspense

  for data fetching
• Mutation hooks for create/update/delete

See

add-feature-hook

skill for patterns.

Step 7: Create Page and Components

Create:

• front/app/{feature}/page.tsx

  - Auth wrapper

• front/app/{feature}/loading.tsx

  - Loading state

• front/components/{feature}/{Feature}Content.tsx

  - Data fetching + UI

See

add-protected-page

skill for patterns.

Step 8: Update Middleware (if needed)

// front/middleware.ts
const isProtectedRoute = createRouteMatcher([
  '/dashboard(.*)',
  // ... existing routes
  '/{feature}(.*)', // Add new route
]);

Phase 3: Quality Checks

Step 9: Run All Quality Checks

Backend:

cd back && task format && task tests

Frontend:

cd front && pnpm type-check && pnpm lint && pnpm test

Checklist

• Backend module created with Clean Architecture
• Database migration created and applied
• Backend tests passing
• API types generated in frontend
• Feature hook created
• Page and components created
• Middleware updated (if protected route)
• All quality checks passing

Related Skills

• create-api-module

  - Backend module creation

• create-db-migration

  - Database migrations

• add-protected-page

  - Frontend page creation

• add-feature-hook

  - Frontend API hooks

• backend-quality

  - Backend quality checks

• frontend-quality

  - Frontend quality checks