📁 Mosaik Folder Structure & Naming Conventions

This guide documents the folder structure and file naming conventions used in the Mosaik framework.

Mosaik follows a slot-driven, themeable, and hybrid-rendering architecture that encourages clean separation of concerns, modularity, and full SSR with interactivity.

---

🧠 Overview

src/
├── app/                 # Next.js app directory (layouts, routes, SSR)
│   └── mosaik/          # Main application namespace
│       ├── [...section]/
│       │   └── page.tsx        # Entry point for pages in a section
│       ├── layout.tsx          # Global app layout (SSR + slots)
│       ├── routes.ts           # Async + static route declarations
│       ├── state.ts            # Initial state definition
│       └── reducers.ts         # App reducer for global state
├── blocks/             # Smart components (business logic + slots)
│   ├── ActionBar.tsx           # Uses actions, provides UI
│   ├── ThemedComponent.tsx     # Renders theme-specific components
│   └── hybrid/                 # Hybrid server/client components
│       ├── SidebarContent.tsx         # Server wrapper
│       ├── SidebarContentClient.tsx   # Client logic
│       ├── SidebarActionBar.tsx       # Hydrated version of ActionBar
├── components/         # Dumb/presentational components (unthemed)
│   └── Icon.tsx                # Themed icon helper. Exports used icons.
├── context/            # App-wide providers and hooks
│   └── StateContext.tsx       # Global app state provider (Flux)
├── lib/                # Utility functions and SSR/client helpers
│   ├── hooks/                  # React hooks
│   │   └── useThemedComponent.ts
│   ├── server/
│   │   └── getThemedComponent.ts     # Loads SSR component for theme
│   └── util/
│       └── getServerUIState.ts       # Parses UI state from cookies
├── layouts/            # Layout components for views/pages
│   └── DesktopColLayout.tsx         # Main desktop layout using slots
├── slots/              # Slot definitions for each layout type
│   ├── getDesktopSlots.tsx     # Desktop layout slots
│   ├── getSectionSlots.tsx     # Section-specific slots
└── themes/             # Theme definitions (one folder per theme)
    └── default/
        └── {ComponentName}.tsx    # Tiny, purely visual

---

📂 Folder Purposes

app/

Root application entrypoints for Next.js routing. Includes layouts and page-level handlers.

• layout.tsx: Wraps the entire app (SSR) and injects global context + slots
• routes.ts: Async + static route list for slot navigation
• [...section]/: Dynamic route matcher for content pages by section

---

blocks/

Smart components that manage logic, context, or action orchestration.

• Each *.tsx file is a block, typically using ThemedComponent, actions, or slots
• hybrid/: Special folder for hybrid rendering (SSR + hydration)
  • ComponentName.tsx: Server wrapper
  • ComponentNameClient.tsx: Hydrated client logic

---

components/

Dumb, purely presentational components. Stateless, small, and styled via Tailwind or themes.

• Should not depend on context or logic
• Often wrapped by blocks/

---

context/

React contexts and providers, typically for app-wide state like StateProvider.

• Follows a Redux-like pattern using actions and effects
• Hydrated via cookies or server context

---

lib/

Utilities, shared helpers, and side-effect managers.

• hooks/: Custom React hooks
• server/: Server-only logic (e.g. getThemedComponent)
• effects/: Components that trigger app logic on mount or update
• util/: Shared logic like reading cookies or parsing UI state

---

layouts/

Layout shell components that use slots to arrange UI.

• Purely structural — they don’t know about logic or theming
• Used inside app/ layouts

---

modules/

Feature bundles that compose logic, slots, and UI into coherent modules.

• e.g. App.tsx: wraps the whole app in providers
• Slot.tsx: injects slot content into layout

---

slots/

Functions that return slot definitions as JSX.

• Each getXSlots.tsx file describes what content goes into which slot
• Allows server rendering of layout compositions based on context

---

themes/

Purely visual. Themed components, selected by name.

• Loaded dynamically by ThemedComponent
• Structure: themes/{themeName}/{ComponentName}.tsx

---

✅ Naming Conventions

Name Type	Convention	Example
Block	PascalCase .tsx	ActionBar.tsx
Hybrid Component	ComponentName.tsx (SSR)	SidebarContent.tsx
Hybrid Client	ComponentNameClient.tsx	SidebarContentClient.tsx
Slot Getter	getXSlots.tsx	getDesktopSlots.tsx
Theme Component	Matches block name	themes/default/ActionBar.tsx

---

🔗 Learn More

Read the full architecture docs at:

👉 https://mosaik.javascript.moe/mosaik/slots-blocks-and-components

---

v0.0.1 — Mosaik Architecture Guide