Directory Architecture

The Whole Workspace

The workspace root itself is not a git repository; it holds four independent repositories plus design documents.

design/
├── heineken-survey-design-backend/    # API server (Hono + Bun + Drizzle / PostgreSQL)
├── heineken-survey-design-frontend/   # Web UI (Next.js 15 App Router)
├── Lab-web-extension/                 # Chrome extension (Plasmo)
├── heineken-survey-design-docs/       # This documentation (MkDocs Material)
├── integration-tests/                 # Playwright integration tests against dev
├── cs-api-logs/                       # Real API traffic from the CS editing screen
└── *.md                               # Implementation plans and CS gap analysis

Directory	Description
heineken-survey-design-backend/	REST API running on AWS Lambda as a container image
heineken-survey-design-frontend/	The Web UI operated by survey designers
Lab-web-extension/	The Chrome extension that pushes into and imports from Creative Survey
heineken-survey-design-docs/	This documentation site
integration-tests/	Playwright tests against the dev environment (an independent directory)
cs-api-logs/	Real logs collected to reverse-engineer the CS API

Design Documents at the Root

File	Contents
branch-logic-current-state-and-cs-diff.md	Current state of branching and the gap against CS; findings from real traffic
branch-cs-parity-implementation-plan.md	The CS parity implementation plan and its phases
free-text-multi-fields-implementation-plan.md	Implementation plan for multiple FA input fields
text-matrix-implementation-plan.md	Implementation plan for the text matrix configuration UI
cs-api-log-collection-guide.md	Procedure for collecting real CS logs
cs-import-test-cases.md	Test cases for pushing into CS (the CP / I / R checklists)

backend

heineken-survey-design-backend/
├── src/
│   ├── index.ts                  # Entry point for local startup
│   ├── lambda.ts                 # Entry point for AWS Lambda
│   ├── migrate-handler.ts        # Entry point for the migration Lambda
│   ├── app.ts                    # createApp(): auth middleware and router registration
│   ├── routes/                   # Route definitions and handlers
│   ├── repositories/             # Data access layer (permissions, transactions)
│   ├── db/                       # Drizzle schema, types, connection
│   ├── lib/                      # Auth, OpenAPI schemas, shared helpers
│   ├── types/                    # Domain types
│   ├── scripts/                  # OpenAPI export, migrations, seed
│   └── test/                     # Test helpers
├── drizzle/                      # Generated migration SQL
├── openapi.json                  # Exported OpenAPI document
├── Dockerfile                    # Container image for the API Lambda
└── Dockerfile.migration          # Container image for the migration Lambda

Directory	Description
src/routes/	Route definitions per resource: surveys / sections / questions / versions / permissions / question-library / users / imports
src/repositories/	survey-store.ts (everything around surveys) and import-store.ts (external imports). DB access and permission checks live here
src/db/	schema.ts (the source of truth for the DB), models.ts (inferred types), client.ts (connection)
src/lib/	auth.ts (user resolution, admin checks), openapi-schemas.ts (Zod schemas), openapi.ts, renumber-questions.ts (question-code renumbering, a pure function)
src/types/domain.ts	Domain types shared between the API and the application

Tests live next to their target as *.test.ts (e.g. src/app.test.ts).

frontend

No src/; app/, components/, and lib/ sit at the repository root.

heineken-survey-design-frontend/
├── app/                          # App Router
│   ├── login/                    # Login
│   ├── surveys/                  # List, create, detail, sections, preview
│   ├── library/                  # Question library
│   └── api/auth/[...nextauth]/   # next-auth handler
├── components/
│   ├── app-shell/                # Shared shell with sidebar and header
│   ├── common/                   # Generic UI (buttons, badges, dialogs, …)
│   ├── providers/                # Auth and TanStack Query providers
│   ├── surveys/                  # Survey, section, question, and preview screens
│   └── library/                  # Question library screen
├── lib/
│   ├── api/                      # API client generated by orval (do not edit)
│   ├── orval/client.ts           # customFetch (attaches shared headers)
│   ├── surveys/                  # Domain logic such as branch evaluation and validation
│   └── format/                   # Utilities such as date formatting
├── styles/                       # Shared SCSS
├── types/                        # Shared types
├── scripts/                      # OpenAPI normalization, orval patch, husky setup
├── _templates/                   # hygen component scaffolding
├── middleware.ts                 # Auth protection for /surveys/* and /library/*
└── Dockerfile                    # Container image for App Runner

Directory	Description
app/	Routing. page.tsx (server) and page-client.tsx (client) are placed as pairs
components/	One component per directory: index.tsx + index.module.scss
lib/surveys/	Domain logic independent of the UI: branch evaluation, validation, custom hooks
lib/api/	orval output. Do not edit

Screens and Their Implementations

Screen	Path	Implementation
Login	/login	components/auth/login-page-client/
Survey list	/surveys	components/surveys/surveys-page-client/
Create	/surveys/new	components/surveys/new-survey-client/, survey-theme-form/
Survey detail	/surveys/[id]	components/surveys/survey-detail-client/, survey-permission-panel/, survey-version-panel/
Section list	/surveys/[id]/sections	components/surveys/section-list-client/
Section detail	/surveys/[id]/sections/[sectionId]	components/surveys/section-detail-client/
Preview	/surveys/[id]/preview	components/surveys/survey-preview/
Question library	/library	components/library/question-library-page-client/

Chrome Extension

Lab-web-extension/
├── src/
│   ├── background.ts                       # Background script
│   ├── popup/                              # Extension popup UI
│   ├── contents/
│   │   ├── creative-survey-overlay.tsx     # Operation panel overlaid on the CS screen
│   │   └── cs-api-logger.ts                # Records CS API traffic
│   ├── components/creative-survey/         # Push UI and API log panel
│   ├── providers/                          # Theme / SurveyUploader providers
│   ├── types/                              # Types for the CS API and the design tool JSON
│   └── utils/creative-survey/
│       ├── api.ts                          # CS API client
│       ├── constants.ts                    # answer_type and API URL
│       ├── plan/build-import-plan.ts       # Exported JSON → CS push plan (pure functions)
│       ├── execute-import-plan.ts           # Calls the CS API following the plan
│       └── reset-survey.ts                 # Resets a questionnaire on the CS side
└── cs-import-test-cases.md                 # Test cases for pushing into CS

Pushing into CS separates conversion (building the plan) from execution (calling the API). Because the conversion is a pure function, it can be tested exhaustively with Vitest without calling the CS API.

flowchart LR
    Json[Questionnaire JSON] --> Build[build-import-plan.ts<br/>pure functions]
    Build --> Plan[Push plan]
    Plan --> Exec[execute-import-plan.ts]
    Exec --> CS[(Creative Survey API)]

integration-tests

integration-tests/
├── config.ts                     # dev URLs and the API account
├── playwright.config.ts          # Playwright config (workers: 1, headless: false)
├── tests/
│   ├── 00-smoke.spec.ts          # Connectivity check against dev
│   ├── 01-build-survey.spec.ts   # Survey construction (CP1–CP13)
│   └── 02-preview-run.spec.ts    # Preview runs (R1–R28)
├── pages/                        # Screen operations (question editor / branch / visibility / preview)
├── lib/                          # dev API calls, run logic, wait helpers
├── fixtures/scenario.ts          # Definition of the question table (Q1–Q13)
└── scripts/                      # Saving auth state, cleanup, CS log comparison

docs (this site)

heineken-survey-design-docs/
├── mkdocs.yml                    # Site configuration, navigation, i18n
├── pyproject.toml                # MkDocs dependencies (managed by uv)
└── docs/
    ├── home.{ja,en}.md
    ├── link.{ja,en}.md
    ├── business-domain/          # Product, actors, features, data model
    └── development/              # Setup, API, DB, infrastructure, conventions

Japanese pages are *.ja.md and English pages are *.en.md, placed in the same directory (the suffix scheme of mkdocs-static-i18n).

Where to Put New Files

What you are adding	Where it goes
An API endpoint	backend src/routes/<resource>.ts (register it in src/app.ts for a new resource)
DB access	backend src/repositories/survey-store.ts (import-store.ts for external imports)
A table definition	backend src/db/schema.ts, then bun run db:generate
Request / response schemas	backend src/lib/openapi-schemas.ts
Domain types	backend src/types/domain.ts
A screen	frontend app/<path>/page.tsx + page-client.tsx, with the body in components/<domain>/
A generic UI component	frontend components/common/ (scaffold with bun run new:common)
A screen-specific component	frontend components/<domain>/ (bun run new:component)
Logic independent of the UI	frontend lib/surveys/ as a pure function, tested with Vitest
CS conversion logic	extension src/utils/creative-survey/plan/build-import-plan.ts plus its .test.ts
An integration test scenario	integration-tests/tests/ and fixtures/scenario.ts