Project Structure

MinuteShip follows a modular architecture based on TanStack Router with file-based routing, focusing on scalability and maintainability.

Root Directory Structure

• src/
  • api/: API route handlers and server logic
  • auth/: Better Auth configuration and utilities
  • cache/: Server-side cache module
  • components/: UI components organized by feature
  • config/: Configuration files for the application
  • db/: Database schema, migrations, and utilities
  • env/: Environment variable validation (client/server)
  • hooks/: Custom React hooks
  • lib/: Core application logic and utilities
  • mail/: Email templates and sending module
  • locale/: Paraglide middleware and generated runtime
  • middlewares/: Route middlewares
  • newsletter/: Newsletter subscription module
  • notification/: Notification module
  • payment/: Payment module
  • storage/: File storage module
  • routes/: TanStack Router file-based routes
  • types/: TypeScript type definitions
  • styles.css: Global styles and Tailwind CSS configuration
• content/
  • blog/: Blog posts in Markdown format
  • pages/: Custom pages in Markdown format (legal pages etc.)
  • changelog/: Changelog entries in Markdown format
• public/: Static assets served from the root
• project.inlang/: Locale configuration and messages/en.json, messages/zh.json
• tests/: Vitest unit tests and Playwright E2E tests
• AGENTS.md: Project context and conventions for coding assistants
• scripts/: Utility scripts
• biome.json: Biome linter and formatter configuration
• content-collections.ts: Content Collections configuration
• drizzle.config.ts: Drizzle ORM configuration (remote)
• drizzle.config.local.ts: Drizzle ORM configuration (local)
• vitest.config.ts: Vitest unit test configuration
• playwright.config.ts: Local browser test configuration
• playwright.production.config.ts: Built Worker smoke test configuration
• vite.config.ts: Vite configuration
• wrangler.jsonc: Cloudflare Workers configuration (D1, R2, KV bindings)

Key Files

• vite.config.ts: Vite configuration with TanStack Start, Cloudflare, Tailwind CSS, and Content Collections plugins
• wrangler.jsonc: Cloudflare Workers configuration including D1 database, R2 storage, and KV cache bindings
• content-collections.ts: Content Collections configuration for blog, legal pages, and changelog
• drizzle.config.ts: Drizzle ORM configuration for the database
• biome.json: Biome linter and formatter configuration
• .env.example: Template for environment variables

Key Directories

/src/api Directory

Server-side API logic organized by feature:

• ai.ts: Workers AI and fal.ai server functions
• contact.ts: Contact form handling
• newsletter.ts: Newsletter subscription logic
• payment.ts: Payment processing logic
• user-files.ts: User file management logic
• users.ts: User management logic

/src/lib Directory

Core application logic and utilities:

• blog.ts: Blog utilities
• changelog.ts: Changelog utilities
• formatter.ts: Data formatting utilities
• markdown.ts: Markdown processing utilities
• pages.ts: Pages utilities
• price-plan.ts: Price plan utilities
• routes.ts: Application route definitions
• seo.ts: SEO metadata utilities
• urls.ts: URL-related utilities
• utils.ts: General utilities

/src/routes Directory

The routes directory follows TanStack Router file-based routing convention:

• __root.tsx: Root layout with Navbar, Footer, ThemeProvider, Analytics, etc.
• index.tsx: Homepage
• auth/
  • login.tsx: Login page
  • register.tsx: Register page
  • forgot-password.tsx: Forgot password page
  • reset-password.tsx: Reset password page
  • error.tsx: Auth error page
• dashboard/
  • index.tsx: Dashboard page
• settings/
  • index.tsx: Settings index
  • profile.tsx: User profile settings
  • security.tsx: Security settings
  • billing.tsx: Billing settings
  • payment.tsx: Payment settings
  • notifications.tsx: Notification preferences
  • apikeys.tsx: API keys management
  • files.tsx: File management
• admin/
  • users.tsx: Admin user management
• (pages)/
  • pricing.tsx: Pricing page
  • about.tsx: About page
  • contact.tsx: Contact page
  • changelog.tsx: Changelog page
  • roadmap.tsx: Roadmap page
  • ai.tsx: AI playground
  • waitlist.tsx: Waitlist page
• (legals)/
  • privacy.tsx: Privacy policy
  • terms.tsx: Terms of service
  • cookie.tsx: Cookie policy
• blog/
  • index.tsx: Blog listing page
  • $slug.tsx: Blog post page
• api/
  • auth/
    • $.ts: Better Auth API handler
  • webhooks/
    • stripe.ts: Stripe webhook handler
    • creem.ts: Creem webhook handler
    • waffo.ts: Waffo webhook handler
  • storage/
    • file.ts: File upload/download handler

/src/components Directory

Components are organized by feature and purpose for better maintainability:

Shared Components

Shared components are reusable across the application and organized in dedicated directories:

• ui/: Shadcn UI components like buttons, inputs, etc.
• blocks/: Marketing page blocks (homepage, features, etc.)
• layout/: Layout components like navbar, footer, etc.
• shared/: Other shared components
• theme/: Theme provider and toggle
• analytics/: Analytics components
• chatbox/: Chatbox components (Crisp)

Feature Components

The components directory is organized by feature, making it easy to locate and maintain components related to specific features like authentication, blog, dashboard, etc.

• admin/: Admin panel components
• auth/: Authentication related components
• blog/: Blog related components
• changelog/: Changelog related components
• contact/: Contact related components
• dashboard/: Dashboard related components
• payment/: Payment related components
• pricing/: Pricing related components
• settings/: User settings related components
• waitlist/: Waitlist related components

Next Steps

Now that you understand the project structure, explore these related topics:

• IDE Setup: Configure your development environment
• Environment Setup: Configure environment variables
• Getting Started: MinuteShip template getting started guide
• Updating the Codebase: Keep your project codebase up to date