The Solo Mom Project

The Solo Mom Project is a Next.js application for the SMC community. It combines:

• a public resource directory
• a blog and editorial publishing surface
• admin moderation and curation tools
• Neon-backed data workflows
• AI-assisted enrichment and taxonomy operations

DOCS/ is the documentation source of truth. The root README is meant to be the fastest orientation layer for a human collaborator or an agent.

Quick Start

1. Install dependencies:

pnpm i

2. Copy envs and set at minimum:

cp .env.example .env.local

Required:

• DATABASE_URL

Common optional envs:

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• R2_ENDPOINT
• R2_ACCESS_KEY_ID
• R2_SECRET_ACCESS_KEY
• R2_BUCKET
• R2_PUBLIC_BASE_URL
• NEXT_PUBLIC_SITE_URL

3. Run the baseline migration:

pnpm db:migrate:neon

4. Start the app:

pnpm dev

5. Open http://localhost:3000

The first authenticated user is auto-promoted to admin.

Repo Map

app/            Next.js app router surfaces
components/     UI and feature components
lib/            shared runtime/domain logic
  auth/         Better Auth server, client, and error helpers
  blog/         blog feed, markdown, field contract, and types
  editorial/    editorial corpus, retrieval, and content-ops helpers
  media/        placeholder-image helpers
  resources/    resource feed, URL, contact, contract, card, and duplicate helpers
  server/       server-only product/taxonomy helpers
  site/         SEO config and analytics helpers
  storage/      R2 upload and presign helpers
  taxonomy/     taxonomy resolution, routing, policy, and theming
  style-guide/  style-guide manifest and preview support data
  workflow/     permission and approval helpers
db/             Neon schema, migrations, seed pipeline
taxonomy/       canonical taxonomy spec and generated JSON artifact
scripts/        operator tooling
  blog/         blog-specific seed and maintenance scripts
  compat/       runtime compatibility shims for Node-based script execution
  db/           DB checks, migrations, hygiene, cleanup
  editorial/    WhatsApp intake, retrieval, content-ops, and review scripts
  taxonomy/     taxonomy normalization, migration, audit tools
  docs/         docs manifest/frontmatter/link tooling
  evals/        evaluation harnesses and experiment runners
  qa/           accessibility and mobile-surface checks
  style-guide/  component catalog and usage-audit generators
tests/          unit and integration tests
e2e/            Playwright coverage
perf/           performance budgets and Lighthouse automation
DOCS/           canonical docs and project planning
docs-site/      local VitePress wrapper for DOCS
artifacts/      durable review/audit artifacts worth keeping in repo
tmp/ output/    local/generated working directories

Core Commands

App:

• pnpm dev
• pnpm build
• pnpm start
• pnpm lint
• pnpm check-types

Tests:

• pnpm test
• pnpm test:e2e
• pnpm test:e2e:admin
• pnpm test:e2e:full

DB and taxonomy:

• pnpm db:migrate:neon
• pnpm db:migrate:neon:all
• pnpm db:check:neon
• pnpm db:normalize:taxonomy
• pnpm db:prune:taxonomy
• pnpm db:hygiene:dry-run
• pnpm db:hygiene:apply
• pnpm db:report:website-duplicates:strict

Seed and quality:

• pnpm seed:neon
• pnpm seed:neon:latest
• pnpm check:routes
• pnpm check:seo
• pnpm check:a11y:public-surfaces
• pnpm check:mobile-surfaces

Docs:

• pnpm docs:dev
• pnpm docs:build
• pnpm docs:manifest
• pnpm docs:links
• pnpm docs:timestamp

Where To Start

If you are new to the repo, read in this order:

1. AGENTS.md
2. CHANGELOG.md
3. ROADMAP.md
4. DOCS/index.md
5. DOCS/development/architecture-overview.md
6. DOCS/development/operations-and-automations.md
7. DOCS/PROJECTS/completed/3036_editorial-platform-architecture-and-repo-boundaries.md
8. lib/README.md
9. scripts/README.md
10. app/README.md

Current Architecture Direction

The repo is intentionally staying as one product repository.

Current long-term organization posture:

• product runtime stays in app/, components/, and lib/
• script lanes are grouped by purpose under scripts/blog/, scripts/compat/, scripts/db/, scripts/docs/, scripts/evals/, scripts/qa/, scripts/style-guide/, and scripts/taxonomy/
• editorial operator work now lives alongside those lanes under scripts/editorial/
• the first lib/ regrouping passes are now in place under lib/auth/, lib/blog/, lib/editorial/, lib/resources/, lib/site/, lib/media/, and lib/storage/
• new domain logic should prefer an existing lib/*/ folder before adding more flat lib/*.ts files
• durable evidence belongs in artifacts/
• local/generated material should stay out of the source tree when possible
• future editorial-system work will extend this repo rather than split into a separate codebase
• 3036 is now completed; it defines the repo-wide structure and the editorial handoff boundary, but not the downstream feature implementation
• the first editorial-governance slice is now live in code: blog review-gate fields, review-state/byline metadata, admin review-queue surfaces, and reviewer decision linkage are implemented; broader provenance and direct brief/draft linkage remain downstream

Docs Source Of Truth

Key docs:

• DOCS/index.md
• DOCS/getting-started/index.md
• DOCS/development/architecture-overview.md
• DOCS/development/scripts-reference.md
• DOCS/development/operations-and-automations.md
• DOCS/features/submission-and-enrichment.md
• DOCS/features/blog.md
• DOCS/PROJECTS/README.md

For active planning and repo-organization work, see:

• DOCS/PROJECTS/active/3035_blog-editorial-ai-and-voice-program.md
• DOCS/PROJECTS/completed/3036_editorial-platform-architecture-and-repo-boundaries.md