A Tour Through cwkPippa-Style Frontend Code

"Open the files in your editor. The patterns are right there. Recognizing them in the wild is the test."

The route as a recipe

This tour is the recipe you'd use on any Pippa-style TypeScript frontend — your own project, an open-source app, or any well-typed React codebase. Five files, in order. Each represents a layer; together they cover the whole shape.

The tour route

1. src/types/index.ts — start here. Every shared type lives in this file: identity unions (like BrainName), record shapes (like Conversation, Message), discriminated unions for events. Reading this file is reading what the system is. Note the literal-union pattern for enums-by-convention, the discriminated union for streaming events, and the optional fields in record interfaces.

2. src/lib/api.ts — the API client. Look at how functions like fetchConversations() declare their return types as Promise<Conversation[]>. Notice the type-only imports from ../types. Notice how errors are typed (unknown in catch, narrowed by instanceof Error).

3. src/hooks/useChat.ts — the central chat hook. This is where SSE streaming happens. Look at the reducer state shape (a discriminated union), the action types (another discriminated union), and how useReducer's state and dispatch are typed through.

4. src/App.tsx — the top-level component. State is lifted here; child components receive typed props. The component tree wires together the chat, sidebar, council, admin, and settings areas.

5. src/components/chat/MessageList.tsx (or any leaf component) — notice how Props are typed inline, how the children are rendered, how callbacks are typed.

What to look for

As you read, identify:

Every literal-union you see (status fields, enum-shaped identifiers).
Every discriminated union (events, actions, results).
Every import type.
Every place narrowing happens via if, switch, or type predicates.
Every place a generic function signature preserves a type through.
Every Promise<T> and what T is.

Reading is the test. If you can read a real Pippa-style frontend and explain what each type is doing, the Quest worked. If something feels opaque, that's the lesson you should re-visit.

Code

The tour route as a checklist·text

# The tour, conceptually — five files, one layer each.

src/types/index.ts         # shared types — what the system is
src/lib/api.ts             # API client — Promise<T> + import type
src/hooks/useChat.ts       # central state — reducer + discriminated union
src/App.tsx                # top-level — state lifting + typed props
src/components/chat/...    # a leaf — inline Props + event handlers

# Walk in order. Hover types in your editor. Trace imports.
# Every TypeScript pattern in this Quest will appear somewhere in the five.

Exercise

Pick a real TypeScript frontend you have access to — your own project or any well-typed React app. Walk the five-file recipe above. For each file, write a one-sentence summary of what it does (in your own words, not by copying a comment). Then identify three TypeScript patterns from this Quest that appear in each file.

Hint

If you can't find three patterns in a file, you're not reading carefully enough — most modern TS frontends use a dozen. Look for: type-only imports, literal-union enums, discriminated unions, narrowing checks, generic functions, Promise<T>, useState typed initial values, custom hook tuples.

A Tour Through cwkPippa-Style Frontend Code

The route as a recipe

The tour route

What to look for

Code

External links

Exercise

Progress

Comments 0