How dose.wiki is built

01 The big picture in numbers

267

Published substance articles

233

Subjective effects

272

Trip reports

~1,400

TS/TSX files in src/

~700

Pipeline scripts in scripts/

Pipelines produce most of the site's content and media. Reading only src/ shows the website, but not the tooling that fills it.

02 System overview

Scrapers and AI workflows supply content; readers submit reports and feedback. Shared server functions connect these inputs and the editor to the database. The public site serves published records, with replication files delivered separately from Cloudflare R2.

03 Tech stack: what each tool is for

04 Repository map: where things live

Four directories hold most code: src/ for the app, server/ for database functions, scripts/ for pipelines, and lib/ for shared server helpers. The rest holds documentation, assets, vendored dependencies, and configuration.

dose.wiki/
├── src/                      · Next.js application
│   ├── app/                  · public pages, /dev, API routes
│   ├── features/             · domain modules
│   ├── components/           · shared layouts, pages, UI primitives
│   ├── schema/               · Zod article schemas
│   ├── data/                 · copy seeds, JSON artifacts, generated maps
│   ├── theme/                · design tokens
│   └── middleware.ts         · /dev access and host policies
├── server/                   · schema.ts and table functions, executed on Postgres
├── scripts/                  · data pipelines (section 08)
│   ├── parsers/  batch/  citations/  prepopulate/
│   ├── replications/  contributors/  chemistry/  legality/
│   ├── data-ops/  migrate/  seed/  build/  deploy/  reports/
│   ├── tools/  perf/  config/  eslint-plugins/
│   └── lib/                  · CLI plumbing, OpenRouter client
├── lib/                      · app and script server helpers
│   ├── data/                 · publicData.* database readers
│   ├── next/                 · route loaders, copy blocks, host policies
│   ├── postgres/             · Drizzle schema and native callable runtime
│   └── auth/  http/  og/  citations/  runtime/
├── vendor/openchemlib/       · vendored molecule-rendering fork
├── public/                   · molecule images, flags, favicons
├── docs/                     · architecture docs, ADRs, operations and workflow guides
├── data/  content/           · datasets with licenses, and every authored prose file
└── README.md  ARCHITECTURE.md  CONTRIBUTING.md  AGENTS.md

Citation auditing and legality research run as editorial agent workflows maintained outside this repository; the runbooks they follow are docs/workflows/citations.md and docs/workflows/legality.md. Other workflow guidance lives beside its scripts or in docs/workflows/.

05 Frontend: routes and feature modules

src/app/ maps URLs to page routes and ~70 API handlers. Page routes fetch data, prepare metadata, and pass content to the rendering logic in src/features/, grouped into 15 domain modules.

NEXT_PUBLIC_SITE_FLAVOR selects dose.wiki or Effect Index at build time. src/config/siteFlavor.ts controls their navigation, wordmarks, and available routes; both publications share content records. Public DoseWiki, editor DoseWiki, and Effect Index are separate build artifacts and deployments. Only the editor carries general admin credentials; public DoseWiki has restricted create-only intake permissions, and Effect Index is read-only.

06 The data layer: what is in the database

server/schema.ts declares the data shapes (~45 in the recorded inventory); most tables have a matching server/<table>.ts query-and-mutation module. The groups below describe purpose, not visibility: editorial records can include public profiles, while content configuration can hold unpublished drafts. Related tables share a row. Stored-record estimates are historical snapshots, distinct from the live published counts above.

07 Four kinds of traffic, one database

Licensing varies by dataset. Base data is CC0, but exports include exceptions: TripSit's terms on substance interactions, third-party replication media in the effect index, and authors' rights on legacy trip reports. See License & reuse.

08 Scripts and pipelines: the third system

Node and Bun scripts parse scraped sources (scripts/parsers/), prepopulate high-confidence fields (scripts/prepopulate/), and draft prose through OpenRouter (scripts/batch/). Citation and legality workflows research and check supporting sources; claims can remain uncited. Editors review the results in /dev. Article text and citations have separate, ongoing review workflows, and each article displays its review status.

Local execution does not imply a local database. Check the target before any write. Production commands require DATA_BACKEND=postgres, an explicit --target or TARGET_POSTGRES_URL, an allowlisted operation, and every command-specific guard. Shared wrappers default to a dry run and require --write, --confirm-write=<operation>, and a matching --expected-deployment where supported. DATA_WRITES_FROZEN=1 blocks writes. Neither credentials nor a successful dry run authorise publication.

scripts/lib/data-ops-run-context.mjs resolves intent-scoped tokens (DATA_ADMIN_TOKEN_<INTENT>); scripts/lib/production-write-command.mjs supplies shared write gates. Migration-style scripts use pre-write backups and scripts/data/audit-logs/. Follow docs/operations/data-credentials.md for native environment diagnostics, the current allowlist, and the exact write procedure.

Workflow families have their own subdirectories and package commands:

• scripts/citations/verdict-*: citation-support audits, run by the citation workflow in docs/workflows/citations.md.
• scripts/legality/: legal-source research, run by the legality workflow in docs/workflows/legality.md.
• scripts/replications/: media intake and R2 migration, the largest family.
• scripts/contributors/: contributor avatars.
• scripts/chemistry/: molecule and chemistry audits.
• scripts/migrate/, scripts/data-ops/: guarded Postgres migration and export tooling.
• scripts/build/: social-card and theme-CSS generators.

scripts/lib/workflow-command-surface.mjs and its sibling citation-command-surface.mjs index runnable commands; package.json defines the npm run entry points.

How substance articles are made explains scraping, verbatim quote extraction, section prompts, citation proposal and auditing, and human review. It publishes unedited extraction and section-generation prompts, but not citation or legality workflow prompts. Published prompts may differ from those used for a particular article.

09 The replications media platform

Replications are artist-made videos, images, and audio recreations of subjective effects. Postgres stores metadata; Cloudflare R2 stores files under content-addressed keys derived from their contents. server/lib/replicationUrls.ts constructs public URLs using REPLICATION_MEDIA_BASE_URL, required in every deployment.

scripts/replications/ uploads and verifies reviewed media before importing metadata, taxonomy, and attribution into Postgres. The Reddit archive follows docs/workflows/replication-intake.md. In Replication Studio, editors curate carousels, substance showcases, and playlists, and reconcile duplicates. Separate provenance and identity records preserve the source history.

substanceGalleries controls pinned and suppressed showcase items; replicationPlaylists supplies ordered sets to gallery drafts; siteConfig stores the Effect Index homepage carousel order. These database edits need no deploy. Public reads use lib/data/publicData.replications.ts, /api/replications/gallery, and /api/replications/showcase; both JSON endpoints are cacheable.

Known artists are credited; unidentified creators are shown as Unattributed. Rights default to unknown, independently of artist attribution. Source posts and posters are retained losslessly. The gallery's fair-use position appears in src/features/replications/replicationsFairUseCopy.ts and License & reuse.

10 Three flows, step by step

Flow A: a reader opens dose.wiki/lsd

Readers usually receive a cached page. When the page is generated or refreshed, this sequence runs:

1. Route

   The server component in src/app/[slug]/page.tsx runs.

2. Fetch

   A lib/next/ loader calls the tagged, cached, read-only lib/data/publicData.* readers.

3. Validate

   lib/data/publicData.substanceContract.ts validates the record against the Zod schemas in src/schema/.

4. Render

   src/features/article/ renders sections, tables, and citations.

5. Serve

   The page includes JSON-LD search metadata and a substance-specific social card. Incremental static regeneration allows refresh after an hour; editor saves also invalidate affected paths and cache tags.

Flow B: an editor saves an article in /dev

1. Edit

   React Hook Form holds edits in src/features/dev/forms/.

2. Collect changes

   save-orchestrator/ collects articles with unsaved changes.

3. Check access and input

   /api/save-article checks the session role, rate limit, and Zod contract.

4. Save

   substanceIndex.saveSubstances writes the changes and creates a changelog entry.

5. Refresh

   Publication invalidates local caches and requests revalidation on public deployments. A toast reports the save result.

Flow C: a reader submits a trip report

1. Write

   /reports/submit collects the report using src/features/reports/submissions/.

2. Check the submission

   /api/trip-report-submissions enforces a rate limit, honeypot, and 128 KB cap. The submitter's IP is stored only as a salted hash.

3. Store privately

   The report enters tripReportSubmissions, not the public catalog.

4. Review

   The /dev Trip Report Portal shows the queued report with a needs-review badge.

5. Approve for publication

   An editor previews the result, assigns authorship, and confirms through /api/trip-report-submissions/[id]/promote.

6. Publish

   A tripReports record makes the report available at /reports/[slug].

11 Recurring vocabulary

Substance article

A structured substance record with about 15 sections, defined by src/schema/ and stored in substanceIndex.

VCode

Custom markup for effect articles, stored with a parsed syntax tree (AST) and rendered by src/features/effects/.

Database

The shared Postgres store for content, editorial records, and pipeline data. A database record is not necessarily public.

Site flavor

The build-time choice of dose.wiki or Effect Index, distinct from the public/editor deployment boundary.

Copy block

A keyed piece of editable site text. getCopy() reads it from copyBlocks, falling back to the checked-in JSON when absent.

12 Where to start reading

For a first pass through the code:

1. README.md, ARCHITECTURE.md: orientation, routes, package commands, and system layout.
2. server/schema.ts: the data model; start with substanceIndex.
3. src/app/[slug]/page.tsx → lib/next/routeLoaders.substances.tsx → lib/data/publicData.* → src/features/article/: follow the public read path in Flow A.
4. src/middleware.ts, auth.ts: host routing, sign-in, and roles. Verify deployment routing with a production-shaped build, not just next dev.
5. src/lib/http/protectedRouteOperation.ts, lib/http/rateLimitPolicy.ts: protected API handling, session roles, named rate limits, and payload caps. Public intake uses separate controls.
6. src/features/dev/save-orchestrator/, src/app/api/save-article/: follow Flow B's saves and audit trail.
7. scripts/lib/workflow-command-surface.mjs: find batch, citation, replication, migration, and sync entry points.