Plan Backend Frontend

Plan Backend/Frontend Feature Implementation

Create a comprehensive implementation plan before writing code. DO NOT proceed with implementation until explicitly told "Go" or "Proceed".

Planning Requirements

1. Examine Existing Implementation

MUST examine existing code - speculation is strictly prohibited.

# Check existing features
ls -la backend/src/api/features/
ls -la frontend/src/features/

2. Specify File Paths

Your plan MUST include specific paths for files to create, modify, and delete.

3. Show Clear Diffs

Focus only on essential changes. Do not include entire file contents.

Backend Architecture

Unidirectional dependency: routes -> usecase -> domain (never reverse)

backend/src/api/features/{feature-name}/
├── domain/
│   ├── model/{entity}.ts        # Domain entities and types
│   ├── service/{service}.ts     # Domain services (optional)
│   └── repository.ts            # Data access interface & implementation
├── usecase/{function-unit}.ts   # Application logic
└── routes/
    ├── index.ts                 # Route definitions
    └── handlers.ts              # HTTP request handlers

Key patterns:

• Dependency injection for testability (external deps as parameters)
• Repository pattern for all database access (direct Prisma calls prohibited in StepFunctions)
• Explicit interfaces for all domain models

For code examples, see references/BACKEND-PATTERNS.md.

Frontend Architecture

Feature-based organization with SWR for data fetching:

frontend/src/features/{feature-name}/
├── hooks/
│   ├── use{Feature}Queries.ts    # GET operations with SWR
│   └── use{Feature}Mutations.ts  # POST/PUT/PATCH/DELETE operations
├── components/{Component}.tsx
└── types/index.ts

Key patterns:

• SWR hooks with automatic caching and revalidation
• Check src/components/ before creating new UI elements
• For styling guidance, use /ui-css-patterns skill

For code examples, see references/FRONTEND-PATTERNS.md.

Plan Template

# Implementation Plan: {Feature Name}

## Files to Create
- `backend/src/api/features/{feature}/domain/model/{entity}.ts`
- `backend/src/api/features/{feature}/domain/repository.ts`
- `backend/src/api/features/{feature}/usecase/{function}.ts`
- `backend/src/api/features/{feature}/routes/index.ts`
- `backend/src/api/features/{feature}/routes/handlers.ts`
- `frontend/src/features/{feature}/hooks/use{Feature}Queries.ts`
- `frontend/src/features/{feature}/hooks/use{Feature}Mutations.ts`

## Files to Modify
- `backend/src/api/index.ts` - Register new routes
- `backend/prisma/schema.prisma` - Add new models (if needed)

## Implementation Steps
1. Backend domain layer
2. Backend use case layer
3. Backend routes layer
4. Frontend hooks
5. Frontend components

## Verification
- Run `/build-and-format`
- Run `/test-database-feature` (if database changes)

After Planning

1. STOP and wait for "Go" or "Proceed" from user 2. After implementation: run /build-and-format 3. If schema changed: run /test-database-feature

Local Backend API Testing

Start backend server with auth bypassed:

cd backend
RAPID_LOCAL_DEV=true npm run dev

Server starts at http://localhost:3000. RAPID_LOCAL_DEV=true bypasses Cognito auth and injects mock user.

# Test endpoints
curl http://localhost:3000/api/health
curl http://localhost:3000/{your-new-endpoint}
curl -X POST http://localhost:3000/{endpoint} -H 'Content-Type: application/json' -d '{"key":"value"}'

Database not running? Start it first:

docker-compose -f assets/local/docker-compose.yml up -d
cd backend && npm run prisma:migrate

Backend Architecture Patterns

Reference implementations for the RAPID backend layered architecture.

Layered Structure

backend/src/api/features/{feature-name}/
├── domain/
│   ├── model/{entity}.ts        # Domain entities and types
│   ├── service/{service}.ts     # Domain services (optional)
│   └── repository.ts            # Data access interface & implementation
├── usecase/{function-unit}.ts   # Application logic
└── routes/
    ├── index.ts                 # Route definitions
    └── handlers.ts              # HTTP request handlers

Domain Layer

model/checklist.ts:

export interface CheckListSetModel {
  id: string;
  name: string;
  description: string;
  documents: ChecklistDocumentModel[];
}

export const CheckListSetDomain = {
  fromCreateRequest: (req: CreateChecklistSetRequest): CheckListSetModel => {
    return {
      id: ulid(),
      name: req.name,
      description: req.description,
      documents: req.documents.map(doc => ({
        id: ulid(),
        name: doc.name,
        s3Key: doc.s3Key
      }))
    };
  }
};

repository.ts:

export interface CheckRepository {
  storeCheckListSet(params: { checkListSet: CheckListSet }): Promise<void>;
  findAllCheckListSets(): Promise<CheckListSetMetaModel[]>;
  findCheckListSetById(id: string): Promise<CheckListSetModel | null>;
}

export const makePrismaCheckRepository = (
  client: PrismaClient = prisma
): CheckRepository => {
  return {
    async storeCheckListSet({ checkListSet }) {
      await client.checkListSet.create({
        data: {
          id: checkListSet.id,
          name: checkListSet.name,
          description: checkListSet.description,
          documents: { create: checkListSet.documents }
        }
      });
    },
    async findAllCheckListSets() {
      return await client.checkListSet.findMany({
        select: { id: true, name: true, createdAt: true }
      });
    }
  };
};

Use Case Layer

export const createChecklistSet = async (params: {
  req: CreateChecklistSetRequest;
  deps?: { repo?: CheckRepository };
}): Promise<void> => {
  const repo = params.deps?.repo || makePrismaCheckRepository();
  const checkListSet = CheckListSetDomain.fromCreateRequest(params.req);
  await repo.storeCheckListSet({ checkListSet });
};

Presentation Layer

routes/index.ts:

export function registerChecklistRoutes(fastify: FastifyInstance): void {
  fastify.get('/checklist-sets', { handler: getAllChecklistSetsHandler });
  fastify.post('/checklist-sets', { handler: createChecklistSetHandler });
}

routes/handlers.ts:

export const createChecklistSetHandler = async (
  request: FastifyRequest<{ Body: CreateChecklistSetRequest }>,
  reply: FastifyReply
): Promise<void> => {
  await createChecklistSet({ req: request.body });
  reply.code(200).send({ success: true, data: {} });
};

Frontend Architecture Patterns

Reference implementations for the RAPID frontend feature-based architecture.

Feature Structure

frontend/src/features/{feature-name}/
├── hooks/
│   ├── use{Feature}Queries.ts    # GET operations with SWR
│   └── use{Feature}Mutations.ts  # POST/PUT/PATCH/DELETE operations
├── components/
│   └── {Component}.tsx            # Feature-specific components
└── types/
    └── index.ts                   # Feature-specific types

API Query Hook (SWR)

import useSWR from 'swr';
import { useApiClient } from '@/hooks/useApiClient';

export const useChecklistSets = () => {
  const { get } = useApiClient();
  return useSWR('/checklist-sets', async () => {
    const response = await get('/checklist-sets');
    return response.data;
  });
};

export const useChecklistSet = (id: string) => {
  const { get } = useApiClient();
  return useSWR(id ? `/checklist-sets/${id}` : null, async () => {
    const response = await get(`/checklist-sets/${id}`);
    return response.data;
  });
};

API Mutation Hook

import { useApiClient } from '@/hooks/useApiClient';
import { mutate } from 'swr';

export const useChecklistMutations = () => {
  const { post, put, del } = useApiClient();

  const createChecklistSet = async (data: CreateChecklistSetRequest) => {
    const response = await post('/checklist-sets', data);
    mutate('/checklist-sets');
    return response.data;
  };

  const deleteChecklistSet = async (id: string) => {
    await del(`/checklist-sets/${id}`);
    mutate('/checklist-sets');
  };

  return { createChecklistSet, deleteChecklistSet };
};