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.tsxModule 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 exportsDecision Guide
| Question | Answer | Location |
|---|---|---|
| Used by 2+ modules? | Yes | shared/ |
| Composes a full view? | Yes | modules/*/pages/ |
| Feature-specific? | Yes | modules/*/components/ |
| Pure function, no side effects? | Yes | shared/utils/ |
| External service integration? | Yes | shared/lib/ |