Architecture

Folder structure, import rules, and how the project is organized.

Architecture

Folder Structure

I've deamed this folder structure, React Atomic Bunker (the next level of React Bulletproof). I highly recommended this folder structure, but you do you, boo boo.

src/
  app/                    # Next.js App Router — routing only
    layout.tsx            # Root layout: fonts, providers
    global.css            # Tailwind v4 theme + design tokens
    (docs)/               # Docs site (this site)
    (home)/               # Marketing pages

  layout/                 # App-level layout components
    Navbar.tsx            # Fixed nav with backdrop blur
    Footer.tsx            # Site footer
    Sidebar.tsx           # Docs sidebar navigation
    MobileMenu.tsx        # Full-screen mobile nav
    DocLayout.tsx         # Doc page wrapper

  ui/                     # Design system primitives
    Button.tsx            # All UI components live here
    icons/                # Icon components
    index.ts              # Barrel export

  components/             # Shared components (PageHero, CardGrid, etc.)
  features/               # Feature modules (blog, portfolio, etc.)
  constants/              # Site-wide constants (brand, nav, etc.)
  utils/                  # Utilities (cn, etc.)
  types/                  # Shared TypeScript types

Import Rules

  • ui/ components are generic — no imports from components/, constants/, features/, or app/.
  • Always import UI from @/ui, never from individual files. Icons from @/ui/icons.
  • Shared components from @/components — reusable pieces like PageHero and CardGrid that aren't UI primitives.
  • Features can import other features (e.g. a blog detail page rendering a newsletter signup), but with three rules:
    • No circular dependencies between features.
    • Cross-feature imports go through the barrel (@/features/newsletter), never internal files.
    • If two features share logic, extract it — promote it to @/components or make it its own small feature.
  • Pages are thin — they import features and lay them out, but don't contain business logic or complex markup.