ArchitectureFolder Structure

Folder Structure

frontend/src/

├── pages/                    # ROUTING LAYER (thin)
│   ├── api/                  # API proxy routes
│   │   ├── sections/         # Section CRUD + navigation proxies
│   │   ├── stories/          # Story CRUD proxies
│   │   └── projects/         # Project CRUD proxies
│   ├── admin/
│   │   └── sections.tsx      # Section management (admin-only)
│   ├── [...slugPath].tsx     # Catch-all dynamic route
│   ├── editor.tsx            # Section-aware content editor
│   └── index.tsx             # Home page

├── modules/                  # FEATURE MODULES
│   ├── stories/              # Story feature
│   │   ├── components/       # StoryCard, StoryDetail, StoryList
│   │   ├── hooks/            # useFetchStory, useFetchStories, useStoryMutations
│   │   └── index.ts          # Public API
│   ├── projects/             # Project feature
│   │   ├── components/       # ProjectCard, ProjectDetail
│   │   └── index.ts
│   ├── editor/               # Content editor
│   │   ├── components/       # StoryEditorForm, ProjectEditorForm, PageEditorForm, RichTextEditor
│   │   ├── hooks/            # useStoryEditor, useProjectEditor
│   │   └── index.ts
│   ├── sections/             # Section management
│   │   ├── hooks/            # useFetchSections, useSectionMutations
│   │   └── index.ts
│   ├── registry/             # Display + content type registries
│   │   ├── displays/         # FeedDisplay, CardGridDisplay, StaticPageDisplay
│   │   ├── hooks/            # useFetchContent
│   │   ├── contentRegistry.ts
│   │   ├── displayRegistry.ts
│   │   ├── types.ts
│   │   └── index.ts
│   ├── engagement/           # Reactions and comments
│   └── static/               # Static pages (About, Contact, Terms, Privacy)

├── shared/                   # CROSS-MODULE CODE
│   ├── components/           # Reusable UI
│   ├── hooks/                # Shared logic
│   ├── lib/                  # Infrastructure (api-client, navigation)
│   ├── types/                # Shared types (api.ts)
│   └── utils/                # Pure functions

├── hooks/                    # APP-LEVEL HOOKS
│   ├── useNavSections.ts     # Navigation cache with invalidation
│   └── useActiveSection.ts   # Active section from URL

├── config/                   # SITE CONFIGURATION
│   ├── siteConfig.ts          # Loader for site.config.json
│   └── types.ts               # SiteConfig type definitions

├── templates/                # CSS-ONLY TEMPLATES
│   ├── CONTRACT.md            # Template requirements spec
│   └── default/               # Default template
│       ├── index.css          # Single entry point
│       └── styles/            # tokens, typography, layout, components

├── rendering/                # SSR PATTERNS
│   ├── server/               # getServerSideProps helpers
│   └── client/               # Client-only patterns

└── layout/                   # APP SHELL
    ├── Layout.tsx
    ├── TopNav.tsx             # Database-driven nav with admin links
    └── Footer.tsx

Module Structure

Each module is self-contained:

modules/stories/
├── components/
│   ├── StoryCard.tsx
│   ├── StoryContent.tsx
│   └── index.ts
├── hooks/
│   ├── useFetchStory.ts
│   └── index.ts
├── pages/
│   ├── StoryPage.tsx
│   └── index.ts
├── types/
│   └── story.ts
└── index.ts                  # Public exports

Decision Guide

QuestionAnswerLocation
Used by 2+ modules?Yesshared/
Composes a full view?Yesmodules/*/pages/
Feature-specific?Yesmodules/*/components/
Pure function, no side effects?Yesshared/utils/
External service integration?Yesshared/lib/