Project structure
The tree is what git tracks in the starter today, with src/, src/pages/ and .github/ opened one level. The table under it is the map from AGENTS.md, the file an agent reads first, so the two never disagree.
zerodirs/├── .agents/├── .github/│ ├── docs/│ └── workflows/├── drizzle/├── integrations/├── public/├── scripts/├── seed/├── src/│ ├── actions/│ ├── assets/│ ├── components/│ ├── config/│ ├── content/│ ├── db/│ ├── features/│ ├── icons/│ ├── islands/│ ├── layouts/│ ├── lib/│ ├── loaders/│ ├── pages/│ │ ├── account/│ │ ├── admin/│ │ ├── api/│ │ ├── auth/│ │ ├── blog/│ │ ├── dashboard/│ │ ├── login/│ │ ├── og/│ │ ├── out/│ │ ├── signup/│ │ ├── submit/│ │ ├── 404.astro│ │ ├── [...path].astro│ │ ├── [advertise].astro│ │ ├── about.astro│ │ ├── index.astro│ │ ├── privacy.astro│ │ ├── robots.txt.ts│ │ ├── rss.xml.ts│ │ ├── search.astro│ │ └── terms.astro│ ├── server/│ ├── styles/│ ├── templates/│ ├── content.config.ts│ ├── env.d.ts│ ├── middleware.ts│ └── worker.ts├── tests/├── .editorconfig├── .env.example├── .gitignore├── .nvmrc├── AGENTS.md├── astro.config.ts├── CHANGELOG.md├── CLAUDE.md├── drizzle.config.ts├── LICENSE├── lighthouserc.cjs├── lighthouserc.mobile.cjs├── package.json├── playwright.config.ts├── pnpm-lock.yaml├── README.md├── site.config.ts├── tsconfig.json├── vitest.config.ts├── vitest.workers.config.ts├── worker-configuration.d.ts└── wrangler.jsoncNothing under node_modules/, dist/, .astro/ or .wrangler/ is tracked: install, build, astro check and the dev server create those.
Where things live
Section titled “Where things live”| Path | What |
|---|---|
site.config.ts |
The one file a buyer edits: brand, routes, categories, tags, tiers, SEO, pSEO, theme, feature flags |
astro.config.ts |
Derived from site.config.ts; adapter, fonts, integrations, env.schema |
src/config/schema.ts |
The zod schema and the ten cross-field rules behind pnpm check:config |
src/config/defaults.ts |
Every default the schema fills in |
src/config/presets.ts |
Theme preset registry (default, warm, mono) plus each preset’s OG hex colours |
src/config/types.ts |
The public SiteConfig type |
src/content/blog/ |
Blog posts |
src/content/pseo/ |
Optional per-slug intro/title overrides for generated pSEO pages |
src/content/schema.ts |
Collection schemas: listingSchema, blogSchema, pseoCopySchema |
src/content.config.ts |
Collection definitions (which loader feeds which schema) |
src/loaders/index.ts |
Which database a build reads: the real one with the three D1 credentials, the local one with none, a failure with some |
src/loaders/d1-local.ts |
The local Miniflare database as a build source, through wrangler d1 execute --local |
src/loaders/normalize.ts |
D1 row → Listing: category check, tag filter, date coercion, isFeatured |
src/pages/[...path].astro |
The only dynamic route; getStaticPaths builds every directory page |
src/pages/ |
Fixed pages: home, search, about, terms, privacy, 404, blog, /rss.xml, /robots.txt, OG endpoint |
src/lib/routes.ts |
The pure route table (buildRoutes, matchers, reserved segments) |
src/lib/paths.ts |
The only URL constructor in the project |
src/lib/seo.ts |
Titles, descriptions, canonicals, noindex, sitemap chunks |
src/templates/ |
One template per page kind; the catch-all dispatches to these |
src/components/listing/Detail.astro |
The listing detail body — the file to edit for “change the detail page”; src/components/listing/BookmarkButton.astro is the Bookmark button it carries with features.accounts |
src/components/ |
Everything else presentational (listing/, category/, blog/, pseo/, seo/, site/, ui/, and ads/ — the four placements site.config.ts ads switches on) |
src/features/pseo/patterns.ts |
The pSEO template registry — a new template’s candidate logic goes here; src/features/pseo/generate.ts handles minItems, collisions, maxPages, siblings and copy, and pseoPages() in src/features/pseo/index.ts is what the routes call |
src/features/og/ |
Build-time OG image rendering (satori + resvg); ogImagePath() in src/features/og/index.ts is the image every template references |
src/features/related.ts |
The related-listings ranking behind the “Related” block on a listing page |
src/styles/global.css |
Tailwind v4 entry: @source allow-list, dark variant, preset imports, @theme inline |
src/styles/presets/ |
One CSS file per theme preset |
src/islands/SearchPanel.tsx |
The only hydrated component in the whole site |
src/db/schema.ts |
The D1 schema. Migrations in drizzle/ are generated from it |
src/loaders/d1.ts |
The D1 loader: the REST client for the real database, and the paging, popularity and store logic both databases share |
src/middleware.ts |
Guards /admin/**, /dashboard/** and /_actions/, reads the submitter session and keeps the header’s zd_user hint cookie in step with it; lazy-imports the DB so prerender stays clean |
src/actions/ |
The four Action namespaces: submit (public), admin, auth (sign in, sign up, reset, the account page’s two forms, sign out) and dashboard (withdrawing a submission) |
src/server/ |
Everything that runs per request: db, env (the only reader of the astro env module), token, admin-auth, submit, queries, meta-fetcher, media, jobs, queue, email/, rebuild/, auth/, dashboard and bookmarks (what the submitter dashboard reads and writes) |
src/pages/submit/ |
The public two-step form and the token-addressed status page |
src/pages/dashboard/ |
Submitter accounts (features.accounts): /dashboard/ and the pages under it — the overview with its searchable table, submissions (upgrade, withdraw), bookmarks, the account page — on src/layouts/Dashboard.astro. src/pages/login/ is the sign-in page (email and password; /login/forgot/ asks for a reset link), src/pages/signup/ the create-account page, src/pages/auth/ the reset form and the Google callback, src/pages/api/bookmarks/ the endpoint the Bookmark button posts to, and src/pages/account/ a permanent redirect from where the dashboard used to be. src/server/auth/ holds sessions, passwords, reset links and the Google exchange |
src/components/account/AuthCard.astro |
The sign-in / sign-up / reset card — the file to edit for “change the login form”. One component behind /login/, /signup/, /login/forgot/, /auth/reset/ and the dialog the header’s account icon opens: src/components/site/LoginDialog.astro is the empty dialog and its inline script, src/pages/login/dialog.astro serves the card to it as a fragment, src/components/account/AccountMenu.astro is what a signed-in visitor gets instead |
src/pages/admin/ |
Login, queue, listing detail, featured, stats |
src/worker.ts |
The Worker entry (main): the adapter’s fetch, plus scheduled running the hourly jobs in src/server/jobs.ts |
integrations/sitemap.ts |
Chunked sitemap |
integrations/pagefind.ts |
Search index, written at astro:build:done |
integrations/budget.ts |
Static-file count against the Cloudflare plan limit |
integrations/seo-report.ts |
Inbound-link / orphan / sitemap audit; can fail the build |
integrations/media.ts |
The /media/[...key] route: the MEDIA bucket served by the Worker, which local builds and astro dev link logos through |
integrations/preview-secrets.ts |
Hands astro preview the secrets in .env: the preview Worker reads dist/server/.dev.vars (the build’s snapshot of .env) and process.env, never the root .env itself |
scripts/ |
The CLI scripts behind the pnpm commands below |
tests/unit/ |
Vitest node tests (vitest.config.ts) |
seed/datasets/ai-tools/ |
The demo dataset: what a fresh clone’s pnpm dev seeds, and what pnpm content:use ai-tools restores. Datasets are seeds; nothing builds from them directly |
public/ |
Copied verbatim into the build: public/favicon.svg, public/og-default.png, public/_headers |
.agents/skills/ |
Task recipes; pnpm skills:sync copies them to .claude/skills/ |
wrangler.jsonc |
Worker name, main, compatibility date, the DB / MEDIA / EMAIL bindings |
.env.example |
The environment, in one file: build-time variables and runtime secrets |
Related
Section titled “Related”- Commands: every
pnpmscript, and which file it runs. - Configuration: the one file in the tree a buyer edits first.