Directory Structure

Relevant source files

The following files were used as context for generating this wiki page: - `vite.config.ts` - `tsconfig.json` - `package.json` - `index.html` - `src/main.tsx` - `src/App.tsx` - `src/pages/Editor.tsx` - `src/components/layout/TopBar.tsx` - `src/components/layout/ToolsSidebar.tsx` - `src/components/sheet/Canvas.tsx` - `src/components/sheet/BlockRenderer.tsx` - `src/store/useSheetStore.ts` - `src/lib/themes.ts` - `src/lib/exportUtils.ts` - `src/index.css` - `components.json`

This document outlines the directory structure of the Character Sheet Maker application, a "Local-First" web app built with React, TypeScript, and Vite. The structure is organized to support a component-based architecture, with clear separation of concerns for state management, utilities, styling, and application pages.

The project uses path aliases to simplify imports. The @/* alias maps to the src/ directory, which is configured in both the Vite and TypeScript configuration files. This convention is used throughout the codebase.

Sources: vite.config.ts:8-12, tsconfig.json:11-13, components.json:13-19

High-Level Overview

The following diagram illustrates the main directories and configuration files at the root of the project.

This diagram shows the top-level structure of the repository.

Root Directory Contents

File / Directory	Description	Source(s)
src/	Contains all the application source code, including components, pages, state, and utilities.	tsconfig.app.json:26
index.html	The main HTML entry point for the application. It contains the <div id="root"></div> where the React app is mounted.	index.html:10-11
package.json	Defines project metadata, dependencies (react, vite, zustand, react-grid-layout), and scripts (dev, build, lint).	package.json
vite.config.ts	Vite configuration file. It sets up the React plugin, Tailwind CSS, and the @/* path alias.	vite.config.ts
tsconfig.json	The root TypeScript configuration file, which references tsconfig.app.json and tsconfig.node.json. It also defines the @/* path alias.	tsconfig.json

src Directory

The src directory is the main container for all application logic. It is structured by feature and functionality type.

This diagram shows the primary folders within the src directory and their relationships.

src/main.tsx

This is the application's entry point. It imports global styles and renders the root App component into the DOM.

• Imports react-grid-layout/css/styles.css and react-resizable/css/styles.css for the grid functionality.
• Imports the main application stylesheet index.css.
• Renders the <App /> component inside <StrictMode>.

Sources: src/main.tsx

src/App.tsx

This component sets up the application's routing using react-router-dom.

• Defines a simple home page component (<Home>).
• Sets up two routes:
  • /: Renders the Home component.
  • /editor/:sheetId: Renders the main Editor page.

Sources: src/App.tsx:15-21

src/pages/

This directory contains top-level page components that correspond to application routes.

• Editor.tsx: The main page for the character sheet editor. It assembles the primary layout components: TopBar, ToolsSidebar, and Canvas. It also manages the open/closed state of the sidebar.

Sources: src/pages/Editor.tsx

src/components/

This is the core directory for all React components, organized into subdirectories based on their domain.

This diagram shows the subdirectories within the components folder.

components/layout/

Components responsible for the overall application layout.

• TopBar.tsx: The header bar containing the sheet title, export options (PNG, PDF), and a dark/light theme toggle.
• ToolsSidebar.tsx: The collapsible sidebar on the left. It provides buttons to add new blocks (text, shapes, etc.) to the canvas and to select a theme. It interacts with the useSheetStore to add blocks and change styles.

Sources: src/components/layout/TopBar.tsx, src/components/layout/ToolsSidebar.tsx

components/sheet/

Components directly related to the character sheet itself.

• Canvas.tsx: The main workspace where the character sheet is built. It uses react-grid-layout to create a responsive, draggable, and resizable grid. It renders all the blocks from the useSheetStore and passes them to the BlockRenderer.
• BlockRenderer.tsx: A crucial component that acts as a dispatcher. It takes a block object and renders the appropriate component based on its type (e.g., header, form-box, shape). It also handles block-specific logic like updating data and removing the block.

Sources: src/components/sheet/Canvas.tsx, src/components/sheet/BlockRenderer.tsx

components/ui/

Generic, reusable UI components, likely based on shadcn/ui.

• dropdown-menu.tsx: A styled dropdown menu component built on top of Radix UI primitives. Used in the TopBar for export options.

Sources: src/components/ui/dropdown-menu.tsx, components.json

src/store/

This directory contains the global state management logic using Zustand.

• useSheetStore.ts: The single source of truth for the character sheet's state. It is a Zustand store that persists its state to localStorage.
  • State: blocks, isCompact, globalStyle.
  • Actions: addBlock, removeBlock, updateLayout, updateBlockData, setTheme.

The Block interface is a key data structure defined here:

// src/store/useSheetStore.ts:18-32
export interface Block {
  i: string; // UID, required by RGL
  x: number;
  y: number;
  w: number;
  h: number;
  type: "text" | "image" | "header" | "form-box" | "shape" | "divider" | "list" | "container";
  data?: any; // The real content (text, url image, values)
  config?: {
    level?: 1 | 2 | 3;
    shapeType?: "square" | "circle" | "rounded" | "heart";
    label?: string;
    zIndex?: "back" | "middle" | "front";
    // Any other config props
  };
}

Sources: src/store/useSheetStore.ts

src/lib/

This directory holds utility functions, constants, and type definitions.

• themes.ts: Defines the visual themes for the character sheets (simple, medieval, cyberpunk). Each theme object contains font families and specific Tailwind CSS classes for different block types.
• exportUtils.ts: Contains functions for exporting the character sheet canvas. It uses html-to-image to generate a PNG and jspdf to create a PDF from that image.
• utils.ts: (Not provided, but referenced) Likely contains utility functions like cn for merging Tailwind classes, as is common in shadcn/ui setups.

Sources: src/lib/themes.ts, src/lib/exportUtils.ts

src/index.css

The main stylesheet for the application.

• Imports Google Fonts required for the different themes (Cinzel, Orbitron, Inter, etc.).
• Includes base Tailwind CSS layers.
• Defines custom CSS variables for the light and dark themes, following the shadcn/ui convention.
• Contains custom utility classes like .bg-graph-paper for the canvas background.

Sources: src/index.css

Component and State Interaction

The following diagram illustrates how the main components interact with the Zustand store to manage the application state.

This sequence shows the flow of adding a new block from the sidebar and how the state change propagates through the system to update the UI.

Sources: src/components/layout/ToolsSidebar.tsx:128, src/store/useSheetStore.ts:80, src/components/sheet/Canvas.tsx:31