Project Structure

Directory Overview

Your Bible follows a clear, organized structure that separates concerns and follows framework conventions.

your-bible/
├── src/                    # Source code
│   ├── actions/           # Server actions
│   ├── components/        # React components
│   ├── db/               # Database configuration
│   ├── hooks/            # Custom React hooks
│   ├── lib/              # Utility libraries
│   ├── queries/          # TanStack Query configs
│   ├── routes/           # File-based routes
│   ├── schemas/          # Zod validation schemas
│   ├── server/           # Server-side utilities
│   ├── styles/           # Global styles
│   └── types/            # TypeScript type definitions
├── convex/                # Convex backend
│   ├── _generated/       # Auto-generated Convex types
│   ├── collections.ts    # Collection mutations/queries
│   ├── notes.ts          # Notes mutations/queries
│   ├── stories.ts        # Story mutations/queries
│   ├── verseCollections.ts
│   └── schema.ts         # Database schema
├── public/                # Static assets
├── vite.config.ts        # Vite configuration
├── tsconfig.json         # TypeScript configuration
└── package.json          # Dependencies

Source Directory (`src/`)

`src/actions/` - Server Actions

Server-side functions that run exclusively on the backend. These actions handle sensitive operations and API calls.

Purpose
Usage
Files

Server actions provide secure backend functionality:

Authentication: Login, signup, session management
API Integration: Bible API requests, AI story generation
Rate Limiting: Check and enforce rate limits
Data Fetching: Server-side data retrieval

These functions have access to environment variables and can perform operations that shouldn’t be exposed to the client.

Server actions are called from client components:

import { fetchBibleChapter } from '@/actions/bible'

const data = await fetchBibleChapter({
  bibleId: 'KJV',
  chapterId: 'GEN.1'
})

They can only be imported and executed from server contexts or via TanStack Query.

Typical server action files:

auth.ts - Authentication actions (login, signup, session)
bible.ts - Bible API interactions
stories.ts - AI story generation
collections.ts - Collection data fetching

`src/components/` - React Components

Organized by feature and purpose for easy navigation and maintenance.

src/components/bible/ - Bible Reading Components

Components for displaying Bible content:

ChapterDisplay: Renders Bible chapter text
VerseHighlight: Highlights selected verses
BibleNavigation: Chapter navigation controls
TranslationSelector: Bible version dropdown

These components handle the core Bible reading experience.

src/components/collections/ - Collection Management

Components for verse collections feature:

CollectionList: Display user collections
CollectionForm: Create/edit collection
VerseCard: Individual verse display
AddToCollection: Add verse button/modal

Integrates with Convex for real-time updates.

src/components/search/ - Search Functionality

Search interface components:

SearchBar: Input and controls
SearchResults: Paginated results display
SearchFilters: Translation and options
HighlightedVerse: Results with highlighted terms

src/components/stories/ - Story Management

AI story generation interface:

StoryForm: Story creation parameters
StoryDisplay: Show generated story
StoryList: User’s stories dashboard
StoryComparison: Side-by-side Bible text and story

src/components/forms/ - Form Components

Reusable form components with TanStack Form:

Form wrappers
Input components
Validation displays
Submit handlers

src/components/ui/ - Reusable UI Components

Shadcn/ui components and custom UI primitives:

Buttons
Dialogs
Dropdowns
Inputs
Tabs
Cards
Tooltips

These are the building blocks for the application’s UI.

src/components/skeletons/ - Loading States

Skeleton screens for loading states:

DefaultSkeleton: Router-level loading
ChapterSkeleton: Bible chapter loading
SearchSkeleton: Search results loading
ListSkeleton: List view loading

Component Organization: The component directory uses feature-based organization, making it easy to find related components and maintain feature boundaries.

`src/routes/` - File-Based Routing

TanStack Router uses file-based routing conventions. Each file represents a route in the application.

__root.tsx

Root Layout ComponentDefines:

HTML document structure
Global head tags (meta, links, title)
Root-level data loading (session)
Context providers (Convex, Query)
Shared layout (Header, Toaster)

// Provides context to all routes
export const Route = createRootRouteWithContext<{
  queryClient: QueryClient,
  convexClient: ConvexReactClient,
  convexQueryClient: ConvexQueryClient
}>()

Route Structure

Common route patterns:

index.tsx - Home page (/)
bible.tsx - Bible reading (/bible)
search.tsx - Search page (/search)
collections.tsx - Collections (/collections)
stories.tsx - Stories (/stories)
auth/ - Auth routes (/auth/*)

Nested routes create nested layouts automatically.

Route Features

Each route file can export:

component: The React component to render
beforeLoad: Server-side data loading (like session check)
loader: Async data fetching before render
head: Page-specific meta tags and title
errorComponent: Error boundary for the route

Example:

export const Route = createFileRoute('/bible')(__{
  component: BiblePage,
  beforeLoad: async () => {
    // Check authentication
  },
  loader: async () => {
    // Load initial data
  },
  head: () => ({
    meta: [{ title: 'Read Bible - Your Bible' }]
  })
})

`src/hooks/` - Custom React Hooks

Reusable React hooks for common functionality:

useBible: Bible data fetching and caching
useCollections: Collection management operations
useAuth: Authentication state and helpers
useNotes: Notes CRUD operations
useStories: Story generation and management

Custom hooks encapsulate business logic and make components cleaner by extracting stateful logic into reusable functions.

`src/lib/` - Utility Libraries

Helper functions and utility modules:

utils.ts: Common utilities (className merging, formatters)
api.ts: API client configuration (Axios instances)
constants.ts: Application-wide constants
helpers.ts: Pure helper functions

`src/queries/` - TanStack Query Configurations

Pre-configured query and mutation options:

// Example query configuration
export const bibleQueries = {
  chapter: (bibleId: string, chapterId: string) => ({
    queryKey: ['bible', bibleId, chapterId],
    queryFn: () => fetchBibleChapter({ bibleId, chapterId })
  })
}

Centralizes query configuration for consistency and reusability.

`src/schemas/` - Zod Validation Schemas

Type-safe validation schemas using Zod:

auth.ts: Login/signup form validation
collection.ts: Collection creation validation
story.ts: Story generation parameters
search.ts: Search query validation

import { z } from 'zod'

export const createCollectionSchema = z.object({
  name: z.string().min(1).max(100),
  description: z.string().optional()
})

`src/server/` - Server-Side Utilities

Server-only utility functions:

Configuration helpers
Server-side data transformations
Backend integrations

`src/styles/` - Global Styles

Global CSS and Tailwind configuration:

app.css: Global styles, Tailwind directives, custom CSS
Font imports
CSS variables
Theme configurations

`src/types/` - TypeScript Type Definitions

Shared TypeScript types and interfaces:

API response types: Bible API, Gemini AI
Database types: Convex schema types
Component prop types: Shared interfaces
Utility types: Generic type helpers

Convex Backend (`convex/`)

The Convex directory contains backend logic and database schema.

schema.ts

Database Schema DefinitionDefines tables and their structure:

Collections table
Notes table
Stories table
Verse collections table

Uses Convex schema builder for type-safe tables.

*.ts Files

Queries and MutationsEach file exports:

Queries: Read data from database
Mutations: Write/update/delete data

Examples:

collections.ts - Collection CRUD
notes.ts - Notes operations
stories.ts - Story management

Convex File Structure

convex/
├── _generated/              # Auto-generated by Convex
│   ├── api.d.ts            # API type definitions
│   ├── dataModel.d.ts      # Database model types
│   └── server.d.ts         # Server helper types
├── collections.ts          # Collection queries/mutations
├── notes.ts                # Notes queries/mutations
├── stories.ts              # Story queries/mutations
├── verseCollections.ts     # Verse management
└── schema.ts               # Database schema

Never edit _generated/ files - These are automatically generated by Convex when you run npx convex dev. Manual changes will be overwritten.

Configuration Files

vite.config.ts
tsconfig.json
package.json

Vite build configuration:

export default defineConfig({
  server: { port: 3000 },
  plugins: [
    tsConfigPaths(),
    tanstackStart({ target: 'vercel' })
  ],
  ssr: {
    noExternal: ['@clerk/tanstack-react-start']
  }
})

Development server on port 3000
TanStack Start plugin configured for Vercel
Path aliases via tsConfigPaths
SSR configuration for external packages

TypeScript compiler configuration:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "target": "ES2022",
    "strictNullChecks": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Modern ES2022 target
React JSX transform
Strict null checks
Path aliases (@/* → src/*)

Project metadata and scripts:

{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build"
  },
  "type": "module"
}

ESM module type
Simple build scripts
All dependencies listed with versions

Code Organization Patterns

Feature-Based Organization

Components organized by feature rather than type:

components/
├── bible/      # All Bible-related components
├── collections/# All collection components
└── stories/    # All story components

Makes it easy to find and maintain related code.

Colocation

Related files are kept together:

Component and its styles
Hooks with their components
Types with their modules

Reduces cognitive load and import paths.

Path Aliases

Use @/ prefix for absolute imports:

// Instead of:
import { Button } from '../../../components/ui/button'

// Use:
import { Button } from '@/components/ui/button'

Cleaner imports and easier refactoring.

Separation of Concerns

Clear boundaries between:

Frontend: Components, hooks, UI
Backend: Actions, Convex functions
Shared: Types, schemas, utilities

Prevents mixing of concerns and improves maintainability.

Import Patterns

Recommended Import Order

// 1. External dependencies
import { useQuery } from '@tanstack/react-query'
import { Link } from '@tanstack/react-router'

// 2. Internal modules (aliased)
import { Button } from '@/components/ui/button'
import { useBible } from '@/hooks/useBible'

// 3. Types
import type { BibleChapter } from '@/types/bible'

// 4. Relative imports (if necessary)
import { helper } from './utils'

This structure promotes scalability, maintainability, and developer productivity by providing clear conventions and organized code boundaries.

Get Started

Core Features

Guides

Architecture

Directory Overview

Source Directory (`src/`)

`src/actions/` - Server Actions

`src/components/` - React Components

`src/routes/` - File-Based Routing

__root.tsx

Route Structure

`src/hooks/` - Custom React Hooks

`src/lib/` - Utility Libraries

`src/queries/` - TanStack Query Configurations

`src/schemas/` - Zod Validation Schemas

`src/server/` - Server-Side Utilities

`src/styles/` - Global Styles

`src/types/` - TypeScript Type Definitions

Convex Backend (`convex/`)

schema.ts

*.ts Files

Configuration Files

Code Organization Patterns

Feature-Based Organization

Colocation

Path Aliases

Separation of Concerns

Import Patterns

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Architecture

​Directory Overview

​Source Directory (src/)

​src/actions/ - Server Actions

​src/components/ - React Components

​src/routes/ - File-Based Routing

__root.tsx

Route Structure

​src/hooks/ - Custom React Hooks

​src/lib/ - Utility Libraries

​src/queries/ - TanStack Query Configurations

​src/schemas/ - Zod Validation Schemas

​src/server/ - Server-Side Utilities

​src/styles/ - Global Styles

​src/types/ - TypeScript Type Definitions

​Convex Backend (convex/)

schema.ts

*.ts Files

​Configuration Files

​Code Organization Patterns

Feature-Based Organization

Colocation

Path Aliases

Separation of Concerns

​Import Patterns

Build docs developers (and LLMs) love

Directory Overview

Source Directory (`src/`)

`src/actions/` - Server Actions

`src/components/` - React Components

`src/routes/` - File-Based Routing

`src/hooks/` - Custom React Hooks

`src/lib/` - Utility Libraries

`src/queries/` - TanStack Query Configurations

`src/schemas/` - Zod Validation Schemas

`src/server/` - Server-Side Utilities

`src/styles/` - Global Styles

`src/types/` - TypeScript Type Definitions

Convex Backend (`convex/`)

Configuration Files

Code Organization Patterns

Import Patterns