Tracing a Feature

How to trace any feature through both codebases. If you need to understand or modify a feature, this page tells you exactly where to look.

The Tracing Method

Every feature in the BizTech app follows the same architecture. To find all the code for any feature, trace through these four layers:

1. Frontend page/component  →  src/pages/ or src/components/
2. Query/fetch call          →  src/queries/ or inline fetchBackend()
3. Backend handler           →  services/{service}/handler.js
4. Database table            →  constants/tables.js → DynamoDB

Worked Example: Events

Let's trace what happens when a user views the event list.

Layer 1: Frontend Page

The entry point is a page file. Event-related pages:

src/pages/index.tsx                           → Home/events list
src/pages/event/[eventId]/[year]/index.tsx    → Single event detail
src/pages/admin/event/create.tsx              → Event creation (admin)
src/pages/admin/event/[eventId]/[year]/       → Event dashboard (admin)

How to find it: Search for the URL path in src/pages/. Next.js file-based routing means the page path = the URL path.

Layer 2: Query Hook

The page imports a query hook that fetches data:

// In the page component
import { useEvents } from '@/queries/events'
const { data: events } = useEvents()

How to find it: Look for useQuery or fetchBackend calls in the page file. The query hook is usually in src/queries/ with a name matching the feature.

The query file tells you exactly which API endpoint is called:

// src/queries/events.ts
queryFn: () =>
  fetchBackend({ endpoint: '/events', method: 'GET', authenticatedCall: false })

Layer 3: Backend Handler

The endpoint /events maps to a service. The routing is defined in sls-multi-gateways.yml:

- srvName: events
  srvPath: events
  srvSource: services/events

So GET /events is handled by services/events/handler.js. Open serverless.yml in that service to see which handler function maps to which path:

functions:
  getAll:
    handler: handler.getAll
    events:
      - http:
          path: events/
          method: get

How to find it: The endpoint path → service directory → serverless.yml → handler function name.

Layer 4: Database Table

The handler calls db.scan(EVENTS_TABLE). The table constant is defined in constants/tables.js:

export const EVENTS_TABLE = 'biztechEvents'

At runtime, db.js appends the environment suffix: biztechEvents (dev) or biztechEventsPROD (production).

Quick-Find Cheat Sheet

If you know any one piece, you can find the rest:

Feature Map: Common Features

Finding Things by Search

"Which service handles this endpoint?"

# In serverless-biztechapp-1/
grep -r "path: events/" services/*/serverless.yml

"Which page calls this API?"

# In bt-web-v2/
grep -r "'/events'" src/queries/ src/pages/ src/lib/

"Which services use this table?"

# In serverless-biztechapp-1/
grep -r "EVENTS_TABLE" services/

"What fields does this table store?"

Look at what the handler's create or put function writes. The DynamoDB tables have no fixed schema — the shape is determined by what the code writes.

Adding to an Existing Feature

When you need to modify a feature:

1. Trace it using the method above — find all four layers
2. Change the backend first if you're adding a new field or endpoint
3. Update the frontend to use the new data/endpoint
4. Test locally: run both the frontend (npm run dev) and backend (npm run start) and verify the full flow
5. Check related features: some features share tables (e.g. registrations are read by both the registration page and the admin dashboard)

See Adding a Feature for the step-by-step guide when building something entirely new.

Related Pages

• Request Execution Path — full request trace through every layer
• Frontend–Backend Integration — the fetchBackend layer
• Endpoint Registry — all 165+ endpoints across every service
• Adding a Feature — how to add a new feature end-to-end