Skip to content

File Structure

Jump to bottom
Temp edited this page Jan 9, 2026 · 5 revisions

File Structure

Project organization and key files in D1 Database Manager.

Overview

D1 Manager follows a modular structure separating frontend (React) and backend (Cloudflare Worker) code with clear organization.

Root Directory

d1-manager/
├── src/                      # Frontend source code
├── worker/                   # Backend source code
├── public/                   # Static assets
├── dist/                     # Build output (git-ignored)
├── node_modules/             # Dependencies (git-ignored)
├── .github/                  # GitHub Actions workflows
├── package.json              # Project dependencies
├── package-lock.json         # Locked dependencies
├── tsconfig.json             # TypeScript root config
├── tsconfig.app.json         # Frontend TS config
├── tsconfig.node.json        # Node.js TS config
├── vite.config.ts            # Vite configuration
├── tailwind.config.js        # Tailwind CSS config
├── postcss.config.js         # PostCSS configuration
├── components.json           # shadcn/ui config
├── wrangler.toml             # Worker production config
├── wrangler.dev.toml         # Development config
├── .env.example              # Environment template
├── .gitignore                # Git ignore rules
├── README.md                 # Project documentation
├── LICENSE                   # MIT license
├── SECURITY.md               # Security policy
├── CONTRIBUTING.md           # Contribution guide
├── CODE_OF_CONDUCT.md        # Community standards
├── DOCKER_README.md          # Docker deployment guide
└── VERSION                   # Version number (1.1.1)

Frontend Structure (src/)

src/
├── components/               # React components
│   ├── ui/                  # shadcn/ui base components
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── dialog.tsx
│   │   ├── input.tsx
│   │   ├── label.tsx
│   │   ├── select.tsx
│   │   ├── checkbox.tsx
│   │   ├── accordion.tsx
│   │   ├── progress.tsx
│   │   └── ...
│   ├── DatabaseView.tsx      # Database table list
│   ├── TableView.tsx         # Table data browser
│   ├── QueryConsole.tsx      # SQL query executor
│   ├── SchemaDesigner.tsx    # Visual table creator
│   ├── FilterBar.tsx         # Row-level filtering
│   ├── ThemeToggle.tsx       # Theme switcher
│   ├── Header.tsx            # App header
│   ├── DatabaseComparison.tsx
│   ├── CrossDatabaseSearch.tsx
│   ├── MigrationWizard.tsx
│   ├── CascadeImpactSimulator.tsx
│   ├── TimeTravelInfo.tsx        # Time Travel tab
│   └── ...
├── contexts/                 # React contexts
│   └── ThemeContext.tsx      # Theme state management
├── hooks/                    # Custom hooks
│   └── useTheme.ts           # Theme hook
├── services/                 # External services
│   ├── api.ts                # API client
│   └── auth.ts               # Authentication helpers
├── lib/                      # Shared libraries
│   └── utils.ts              # Utility functions
├── App.tsx                   # Main app component
├── main.tsx                  # React entry point
└── index.css                 # Global styles + Tailwind

Key Frontend Files

App.tsx - Main application:

  • Routing logic
  • Database list view
  • State management
  • View switching

main.tsx - Entry point:

  • React initialization
  • DOM rendering
  • Theme provider

index.css - Global styles:

  • Tailwind imports
  • CSS variables for theming
  • Global styles

services/api.ts - API client:

  • Centralized API calls
  • Type-safe methods
  • Error handling

contexts/ThemeContext.tsx - Theme management:

  • Light/Dark/System modes
  • LocalStorage persistence
  • CSS class manipulation

Backend Structure (worker/)

worker/
├── routes/                   # API route handlers
│   ├── databases.ts          # Database operations
│   ├── tables.ts             # Table operations
│   ├── queries.ts            # Query execution
│   ├── saved-queries.ts      # Saved queries
│   ├── undo.ts               # Undo/rollback operations
│   ├── jobs.ts               # Job history and events
│   └── time-travel.ts        # Time Travel bookmarks
├── utils/                    # Utility functions
│   ├── auth.ts               # JWT validation
│   ├── cors.ts               # CORS headers
│   ├── helpers.ts            # Helper functions
│   ├── database-tracking.ts  # DB access tracking
│   ├── undo.ts               # Undo/rollback helpers
│   └── time-travel.ts        # Time Travel helpers
├── types/                    # TypeScript types
│   └── index.ts              # Type definitions
├── index.ts                  # Worker entry point
└── schema.sql                # Metadata DB schema

Key Backend Files

index.ts - Worker entry:

  • Request handling
  • Route dispatching
  • Error handling
  • Localhost detection

routes/databases.ts - Database CRUD:

  • List databases
  • Create database
  • Delete database
  • Rename database
  • Bulk operations

routes/tables.ts - Table operations:

  • List tables
  • Get schema/data
  • Create/rename/delete
  • Column management
  • Dependencies

routes/queries.ts - Query execution:

  • Execute SQL
  • Batch queries
  • Query history
  • Validation

utils/auth.ts - Authentication:

  • JWT validation
  • Cloudflare Access integration

utils/cors.ts - CORS management:

  • Allowed origins
  • CORS headers

schema.sql - Metadata database:

  • Query history table
  • Saved queries table
  • Database tracking

Configuration Files

package.json

Purpose: Project metadata and dependencies

Key sections:

  • name: "d1-manager"
  • version: "1.1.1"
  • scripts: Build and dev commands
  • dependencies: Runtime dependencies
  • devDependencies: Development tools

tsconfig.json

Purpose: TypeScript root configuration

Settings:

  • Strict mode enabled
  • ES2020 target
  • Module resolution: bundler
  • Path aliases: @/* → src/*

tsconfig.app.json

Purpose: Frontend TypeScript config

Includes:

  • src/ directory
  • Vite types
  • React types

tsconfig.node.json

Purpose: Node.js tooling TypeScript config

Includes:

  • vite.config.ts
  • Build scripts

vite.config.ts

Purpose: Vite build configuration

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  },
  server: {
    port: 5173
  }
});

tailwind.config.js

Purpose: Tailwind CSS configuration

Settings:

  • Content paths
  • Theme customization
  • Dark mode: 'class'
  • Plugin: tailwindcss-animate

components.json

Purpose: shadcn/ui configuration

Settings:

  • Style: default
  • Base color: slate
  • CSS variables: true
  • TypeScript: true
  • Alias: @/components

wrangler.toml

Purpose: Worker production configuration

Sections:

  • Worker name
  • Main entry point
  • D1 bindings
  • Routes (optional)
  • Assets binding

wrangler.dev.toml

Purpose: Local development configuration

Settings:

  • Development worker name
  • Local mode enabled
  • Mock D1 binding
  • Port: 8787

.env.example

Purpose: Environment variable template

# Worker API URL (local development)
VITE_WORKER_API=http://localhost:8787

Build Output (dist/)

Git-ignored - Generated by npm run build

dist/
├── assets/                   # Bundled JS/CSS
│   ├── index-[hash].js
│   ├── index-[hash].css
│   └── ...
├── index.html                # Entry HTML
└── ...

Documentation Files

README.md

Purpose: Main project documentation

Sections:

  • Features
  • Quick start
  • Installation
  • Configuration
  • Deployment
  • API reference

SECURITY.md

Purpose: Security policy

Sections:

  • Supported versions
  • Reporting vulnerabilities
  • Security best practices
  • Known considerations

CONTRIBUTING.md

Purpose: Contribution guidelines

Sections:

  • Development setup
  • Coding standards
  • Testing
  • Pull request process

LICENSE

Purpose: MIT License text

CODE_OF_CONDUCT.md

Purpose: Community guidelines

DOCKER_README.md

Purpose: Docker deployment instructions

VERSION

Purpose: Single source of truth for version number

Contents: 1.1.1

Git Files

.gitignore

Ignores:

# Dependencies
node_modules/

# Build output
dist/
.wrangler/

# Environment
.env
wrangler.toml

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

.github/

GitHub-specific files:

  • Workflows (CI/CD)
  • Issue templates
  • Pull request templates
  • FUNDING.yml

Development Files

.eslintrc / eslint.config.js

Purpose: Linting configuration

Rules:

  • TypeScript rules
  • React rules
  • React Hooks rules

.prettierrc

Purpose: Code formatting (if used)

postcss.config.js

Purpose: PostCSS configuration

Plugins:

  • tailwindcss
  • autoprefixer

Public Assets

public/
├── favicon.ico
├── logo.svg
└── ...

Static assets served as-is.

File Naming Conventions

Components

Format: PascalCase

Examples:

  • DatabaseView.tsx
  • TableView.tsx
  • QueryConsole.tsx

Utilities

Format: camelCase

Examples:

  • api.ts
  • auth.ts
  • helpers.ts

Configuration

Format: kebab-case or specific conventions

Examples:

  • vite.config.ts
  • tailwind.config.js
  • .env.example

Import Paths

Alias Configuration

tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Usage:

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

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

Next Steps

Need Help? See Troubleshooting or open an issue.

D1 Manager Wiki

🚀 Getting Started

📚 Core Features

🔗 Relationships

🔍 Search & Analysis

📊 Observability

🔧 Advanced Features

⚙️ Development

🌐 Deployment

📖 Reference

Clone this wiki locally