Feature Scaffolding (/feature-scaffold) — express

Stack flavor: express. ← Back to overview

[!NOTE] Use this when creating anything new in the codebase — a feature, page, module, component, API endpoint, or entity that doesn't already exist. For extending an existing page, use /full-stack-extension instead.

Trigger Conditions

• Any request to create, build, add, implement, or introduce new functionality
• Keywords: "Create a new page", "Build a feature", "Add a module for X", "New view", "New endpoint", "Add a section", "Implement X", "I need a new...", "Set up...", "Make a..."
• Also trigger when: the user describes desired behavior that doesn't map to any existing code

---

1. Planning

• [ ] Architecture Check: Review docs/ARCHITECTURE.md for directory structure and naming conventions
• [ ] Schema: Does this feature need new DB tables? If yes, run /db-migration first
• [ ] Routing: Decide the URL path — SalesFocus uses Wouter (not React Router)

2. Backend Scaffold

• [ ] Route file: Create backend/src/routes/[feature].ts

import { Router } from 'express';
import type { NextFunction, Response } from 'express';
import { db } from '../db/index.js';
import { authenticate } from '../middleware/auth.js';
import type { AuthRequest } from '../middleware/auth.js';

const router = Router();

router.get('/', authenticate, async (req: AuthRequest, res: Response, next: NextFunction) => {
    try {
        const data = await db.select().from(featureTable);
        res.json(data);
    } catch (error) {
        next(error); // ALWAYS use next(error) — never manual res.status(500)
    }
});

export default router;

• [ ] Zod validation: Add validation schema to backend/src/validation/[feature].schema.ts
• [ ] Register route: Add to backend/src/server.ts:

  import featureRouter from './routes/[feature].js';
  app.use('/api/[feature]', authenticate, featureRouter);
  

• [ ] Explicit .js extensions: All local imports MUST use .js extension (TypeScript ESM requirement)

3. Frontend Scaffold

• [ ] Service: Create services/domains/[feature]Service.ts (or add methods to services/apiClient.ts if small):

  import apiClient from '../apiClient';
  export const get[Feature]s = () => apiClient.get('/[feature]').then(r => r.data);
  

• [ ] Hook: Create hooks/use[Feature].ts as a domain hook:

  export function use[Feature]() {
      const queryClient = useQueryClient();
      const toast = useToast();
  
      const query = useQuery({
          queryKey: ['[feature]'],
          queryFn: get[Feature]s,
      });
  
      const createMutation = useMutation({
          mutationFn: (data: Create[Feature]Input) => createFeature,
          onSuccess: () => {
              queryClient.invalidateQueries({ queryKey: ['[feature]'] });
              toast.success('[Feature] created');
          },
      });
  
      return {
          [feature]s: query.data || [],
          isLoading: query.isLoading,
          create[Feature]: createMutation.mutateAsync,
      };
  }
  

• [ ] Component: Create components/[Feature]View.tsx or components/[Feature]Page.tsx

• No window.alert() or window.confirm()
• Use <FormattedCurrency /> for money, formatDateLocal() for dates
• Empty states: never blank — use illustration or helpful text

• Loading states: shimmer (animate-pulse on gray blocks)

• [ ] Routing: Add to App.tsx using Wouter:

  import { Route } from 'wouter';
  <Route path="/[feature]" component={[Feature]View} />
  

• [ ] Navigation: If it's a nav item, add to lib/navigation.ts

• Admin-only pages: also add <AdminRoute> wrapper in App.tsx

4. Tests (REQUIRED)

• [ ] Run /test-sync to automatically create tests for all new/changed files
• [ ] Verify: All tests pass before proceeding to verification

5. Verification

• [ ] Integration: Frontend calls backend — verify in browser network tab
• [ ] Design: Run /architecture-review to verify UI compliance (Twycis colors, rounded buttons, etc.)
• [ ] Types: Run cd backend && npm run type-check && npm run type-check