Fullstack Feature

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