Project Structure
A tour of the folders in DirectoryKit and what lives where.
You don't need to understand every folder to ship. This page is a map — come back when you need to know where something lives.
Top-level folders
my-directory/
├── app/ ← Pages and API routes (Next.js App Router)
├── components/ ← Reusable React components
├── config/ ← ALL customization lives here
├── hooks/ ← React hooks (useUser, useFeatures, …)
├── lib/ ← Business logic (DB, auth, payments, email)
├── messages/ ← i18n translations (if enabled)
├── public/ ← Static files (images, fonts)
├── scripts/ ← Utility scripts (db:test, db:migrate, …)
├── supabase/ ← schema.sql — the full database structure
├── types/ ← TypeScript types
├── .env.local ← Your secret keys (never commit this!)
├── CLAUDE.md ← Architecture notes (safe to read)
└── package.json ← Dependencies and scripts
The folders you'll actually edit
config/ — your control panel
This is where you'll spend 90% of your setup time. Each file controls one area:
| File | What you edit here |
|---|---|
site.config.ts | Brand name, tagline, domain, contact emails, social links |
features.config.ts | On/off switches for partners, ratings, AI, i18n, etc. |
plans.config.ts | Your pricing tiers (free, premium, custom) |
themes.config.ts | 14 built-in color themes |
payments.config.ts | Which payment provider to use (Stripe by default) |
email.config.ts | Sender name, reply-to, signature |
analytics.config.ts | GA / PostHog keys (reads from env vars) |
ai.config.ts | AI provider and model for description generation |
i18n.config.ts | Languages the site supports |
directory.config.ts | Page size, sort options, seed categories |
advertising.config.ts | Promotion / sponsor pricing |
marketing.config.ts | The banner at the top of every page |
See the Configuration section for a deep dive on each.
app/ — pages and APIs
Next.js App Router — each folder is a URL path. The project uses route groups (folders in parentheses) to share layouts:
| Route group | Who sees it | Examples |
|---|---|---|
(marketing)/ | Everyone | /, /pricing, /blog, /project/[slug] |
(dashboard)/ | Logged-in users | /dashboard, /submit, /profile, /settings |
(admin)/admin/ | Admins only | /admin, /admin/projects, /admin/categories |
auth/ | Everyone | /auth/signin, /auth/callback |
api/ | Server routes | /api/payments, /api/webhooks/stripe, /api/cron/* |
components/ — UI building blocks
| Subfolder | Contents |
|---|---|
ui/ | shadcn/ui primitives (Button, Card, Dialog, …) — don't edit these by hand |
layout/ | Header, Footer |
directory/ | Project cards, category badges |
forms/ | Image upload, newsletter signup |
admin/ | Admin-only UI (CSV import, promotion dialogs, …) |
marketing/ | Promo banners, partner sections |
shared/ | Providers, error boundary, language switcher |
The folders you'll probably not touch
lib/ — the engine
Business logic. You rarely edit this, but it's where to look if something breaks.
supabase/— database client, auth helpers, MongoDB-style query wrapperpayments/— Stripe integrationvalidations/— Zod schemas (the single source of truth for types)email.ts,notifications.ts,webhooks.ts,rate-limit.ts,seo.ts, …
supabase/schema.sql
The entire database — tables, indexes, permissions, triggers — in a single idempotent SQL file. You run it once when you set up Supabase. See Supabase Setup.
types/
Auto-re-exports types inferred from Zod schemas. You'll import from here:
import type { User, App, Category } from '@/types';The @/ import shortcut
Anywhere in the code, @/ means "the project root." So:
import { siteConfig } from '@/config/site.config';
import { db } from '@/lib/supabase/database';
import { Button } from '@/components/ui/button';
import type { User } from '@/types';Files you should never commit
.env.local— contains secrets. Already in.gitignore.node_modules/— installed dependencies. Already ignored..next/— build output. Already ignored.
What's next
Ready to configure Supabase and go live? Follow the Quick Start tutorial.