DishGraph

DishGraph is a structured food knowledge platform for dishes, recipes, variations, techniques, substitutions, failures, and tested outcomes.

It is designed to help a cook answer more than “what is the recipe?”:

• Which version fits my goal?
• Why does this method work?
• What can I change, and what will change with it?
• What usually goes wrong?
• How can I record and share what happened?

DishGraph is dish-first rather than recipe-first. A dish can have related variants, executable recipes, reusable techniques, contextual substitutions, safety notes, claims, sources, and community test results.

What is in the repository

Area	Location	Purpose
Backend	backend/dishgraph_server	Django and Django REST Framework API, models, services, workers, and tests
Frontend	frontend/apps/web	Next.js application with public pages, search, Cook Mode, My Kitchen, contribution, and editor experiences
Shared frontend packages	frontend/packages	API client, shared TypeScript contracts, and UI primitives
Development infrastructure	docker-compose.dev.yml, docker/	PostgreSQL, Redis, Meilisearch, optional Typesense, backend, worker, and seed services
Product plans	plans/	Product vision, content model, governance, architecture, and roadmap
Implementation plans	implementation/	Phased engineering plans, quality gates, and the current implementation tracker
Operational documentation	docs/	Deployment, search, and infrastructure guidance

Current capabilities

The current codebase includes the foundations and vertical slices for:

• Dish, dish-family, variant, recipe, ingredient, technique, equipment, failure-mode, substitution, claim, evidence, safety, and media records.
• Structured recipe components, outputs, dependencies, execution graphs, scaling, market-aware information, and persistent Cook Mode sessions.
• Public dish, recipe, ingredient, technique, search, and homepage experiences.
• Personal recipes, adaptations, saved content, cooking logs, notes, test results, and community contributions.
• Editor review queues, reports, audit logs, redirects, merge/split operations, promotion/demotion workflows, and source/license declarations.
• AI jobs and reviewed outputs for recipe parsing, tag suggestions, duplicate checks, recipe help, search answers, and editor assistance.
• Multilingual frontend content and backend translation workflows.
• Meilisearch-backed public search, optional semantic retrieval, search telemetry, and a Typesense rollback profile.
• Recipe import/export foundations and Schema.org-oriented interoperability.

The project is still under active implementation. See implementation/TRACKER.md for the current phase and outstanding verification work.

Architecture

The default stack is:

• Next.js, React, TypeScript, and pnpm for the frontend.
• Django 5 and Django REST Framework for the backend API.
• PostgreSQL 16 with pgvector as the source of truth.
• Redis and Celery for asynchronous work.
• Meilisearch for primary search, with Typesense retained as an optional rollback path in development.
• Local media storage in the current deployment setup.
• Configurable AI providers with stored jobs, outputs, and review states.

The backend owns business rules, permissions, privacy boundaries, review transitions, source requirements, and public/private content separation. The frontend consumes shared API contracts rather than duplicating domain rules.

Local development

Prerequisites

• Docker and Docker Compose.
• Node.js with Corepack enabled and pnpm 10.28.2.
• Git.

The supported development path uses Docker for backend infrastructure and pnpm for the frontend.

1. Configure the environment

From the repository root:

cp .env.dev.example .env.dev

Review .env.dev before starting. The example is suitable for local development and uses the console email backend and local development credentials. Do not use it as a production configuration.

2. Start the backend stack and seed data

The Makefile provides the standard workflow:

make setup

This builds the backend image, starts PostgreSQL, Redis, Meilisearch, and Django, waits for the backend health check, and seeds realistic local content.

To start or stop the stack later:

make up
make down

The development services are available at:

Frontend:    http://localhost:3000
Backend API: http://localhost:8000/api/v1/
Admin:       http://localhost:8000/admin/
Health:      http://localhost:8000/api/v1/health/

3. Start the frontend

In a second terminal:

make frontend-install
make frontend-dev

The frontend defaults to the local backend API. To override the API endpoint, set NEXT_PUBLIC_API_BASE_URL; server-side requests can use DISHGRAPH_SERVER_API_BASE_URL.

Seed data

The supported seed command resets and rebuilds the local realistic dataset:

docker compose --env-file .env.dev -f docker-compose.dev.yml \
  exec backend python manage.py seed_realistic

Rebuild the search index as part of seeding when needed:

docker compose --env-file .env.dev -f docker-compose.dev.yml \
  exec backend python manage.py seed_realistic --reindex

Do not run individual seed stages against the shared development database. See backend/dishgraph_server/content/management/commands/README.md for seed data rules.

Testing and quality checks

Run focused backend tests with a fully qualified Django test label:

make test TEST=content.tests.test_phase1_api.Phase1ApiTests

Search tests are intentionally guarded because they need additional infrastructure. Run them only when explicitly intended:

make test TEST=search.tests.test_smart_search.SmartSearchTests ALLOW_SEARCH_TESTS=1

Frontend checks:

make frontend-typecheck
make frontend-lint
make frontend-test
make frontend-build

For a faster serial test run:

make frontend-test-light

The full backend suite is also guarded. Run it deliberately with ALLOW_FULL_TESTS=1 ALLOW_SEARCH_TESTS=1.

Configuration and services

Useful Make targets include:

make help                 Show all available targets
make logs                 Tail all development service logs
make logs-backend         Tail Django logs
make worker               Start the Celery worker
make migrate              Apply migrations
make admin                Create a Django superuser
make reindex-search       Rebuild the public search index
make reset-db             Recreate the development database volume

reset-db and clean are destructive development operations. Use them only when you intend to remove local Docker data.

The optional Typesense rollback service is started with:

make typesense-rollback

Project principles

• Culinary knowledge is data-driven and editor-manageable; workflow mechanics are enforced in code.
• Canonical, community, and personal content have separate ownership and visibility boundaries.
• AI assists with parsing, suggestions, and explanations; it does not publish canonical content by itself.
• Public adapted content requires source and origin declarations.
• Safety, allergen, cultural, and historical claims require appropriate review and evidence.
• Editorial restructuring preserves history through audit records and redirects.
• Private content must not leak through public APIs, search, exports, or cross-user AI retrieval.

Documentation map

• plans/README.md — product principles and planning document map.
• implementation/README.md — implementation phases and engineering contracts.
• implementation/TRACKER.md — current implementation status and verification notes.
• docs/DEPLOYMENT_VPS.md — single-VPS production deployment guide.
• docs/DEPLOYMENT_GOOGLE_FREE_VERCEL.md — deployment option using Google free-tier/Vercel infrastructure.
• docs/search-quality-improvement-plan.md — search quality work and evaluation.

Production notes

Production deployment is documented separately in docs/DEPLOYMENT_VPS.md. Before a public launch, review secrets, HTTPS, email delivery, backups, media storage, search indexing, AI provider configuration, privacy checks, and Django deployment checks.

The implementation tracker currently records successful migration and focused verification work, while full backend replay and the complete manual browser matrix remain outstanding. Treat the repository as active development software until those checks are completed.