Documint

Documint is a repo-native documentation operations product for teams that ship APIs, SDKs, and MCP servers.

The first customer is this repository itself. V1 is deliberately narrow:

• Git is the source of truth.
• documentation changes happen through commits and PRs,
• the public site lives at documint.xyz,
• the backend detects doc drift and exposes a published-docs MCP surface,
• the product is not considered ready until it can keep its own docs current.

Product surfaces

• / marketing and positioning
• /docs published repo-backed documentation
• /app the authenticated operator console for onboarding, traces, findings, patches, PRs, publishes, and tokens
• /p/:workspace/:project/docs/... hosted public docs generated from persisted publish deployments

Stack

• apps/web: Next.js site and dashboard
• src/documint_mcp: Python backend, persistent control plane, drift engine, GitHub App integration, and MCP-style API
• content/docs: published docs content for the self-dogfood project
• alembic: schema migrations for the control-plane database

Local development

1. Install dependencies

npm install
cd apps/web && npm install && cd ../..
python -m pip install -e ".[dev]"

2. Create or migrate the database

documint db upgrade

For local dogfooding, schema creation and self-bootstrap can also be driven by env flags:

• DOCUMINT_AUTO_CREATE_SCHEMA=true
• DOCUMINT_AUTO_BOOTSTRAP_DEFAULTS=true

3. Run the backend

npm run dev:api

4. Run the site

npm run dev:web

The site expects the backend at http://127.0.0.1:8000 by default. Override with DOCUMINT_API_URL if needed.

5. Bootstrap the self project explicitly when auto-bootstrap is off

documint workspaces bootstrap-self

6. Run the queue worker when DOCUMINT_JOB_EXECUTION_MODE=queue

documint worker

7. Run the full dogfood smoke loop

npm run dogfood

This boots the backend and web app, verifies the public pages, runs drift and publish jobs, calls the MCP surface, and posts a signed GitHub webhook delivery against the local API.

Core API routes

• GET /health
• GET /runtime
• GET /me
• GET /workspaces
• POST /workspaces
• GET /snapshot
• GET /projects
• POST /projects
• GET /projects/{project_id}
• POST /projects/{project_id}/rescan
• GET /projects/{project_id}/findings
• POST /projects/{project_id}/findings/{finding_id}/patch
• GET /projects/{project_id}/patches
• GET /projects/{project_id}/patches/{patch_id}
• POST /projects/{project_id}/patches/{patch_id}/pr
• GET /projects/{project_id}/publishes
• GET /projects/{project_id}/activity
• GET /sources
• GET /workspaces/{workspace_id}/tokens
• POST /workspaces/{workspace_id}/tokens
• GET /integrations/github/app
• GET /integrations/github/installations
• GET /integrations/github/installations/{installation_id}/repositories
• POST /integrations/github/installations/{installation_id}/sync
• POST /integrations/github/webhooks
• POST /jobs/drift
• POST /jobs/publish
• POST /auth/cli/exchange
• POST /internal/revalidate
• GET /artifacts/{artifact_id}/trace
• GET /public/projects/{workspace_slug}/{project_slug}/docs/{path}
• GET /mcp
• POST /mcp

MCP tools

• list_projects
• analyze_repository
• detect_doc_drift
• generate_doc_patch
• review_doc_patch
• publish_preview
• explain_doc_trace
• get_project_activity

Release bar

Documint does not onboard external customers until it can do the following on this repo:

1. produce a truthful project snapshot,
2. detect stale documentation from source changes,
3. generate a reviewable patch preview,
4. publish a docs preview,
5. expose those docs through the MCP surface.

Deployment shape

• Deploy apps/web to Vercel with the project root directory set to apps/web.
• Deploy the Python backend to Railway from the repository root using railway.json and the root Dockerfile.
• Point DOCUMINT_API_URL at the public backend origin for the dashboard.
• Set API_BASE_URL, GITHUB_WEBHOOK_SECRET, GITHUB_APP_PRIVATE_KEY, and DOCUMINT_SELF_BOOTSTRAP_INSTALLATION_ID before configuring the GitHub App webhook.
• Set Clerk env vars in both web and backend runtimes:
  • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
  • CLERK_SECRET_KEY
  • CLERK_JWKS_URL
  • CLERK_ISSUER
  • CLERK_AUDIENCE
• Set DOCUMINT_FRONTEND_REVALIDATE_URL, DOCUMINT_FRONTEND_REVALIDATE_SECRET, and DOCUMINT_INTERNAL_REVALIDATE_SECRET so publish jobs can invalidate hosted docs pages.
• Set PUBLIC_BASE_URL=https://documint.xyz, APP_BASE_URL=https://documint.xyz/app, and DOCUMINT_DEPLOY_COMMIT if your runtime does not expose git metadata.
• For a local containerized stack, run docker compose up --build.

Production proof

• /runtime must report the deployed provider, environment, and commit source.
• /app must show live api, not fallback data.
• npm run dogfood now verifies the live dashboard path as part of the self-test.

GitHub App loop

Documint V1 treats GitHub as the first event source for self-dogfooding:

1. create a GitHub App with push, pull_request, release, installation, and installation_repositories events,
2. set the webhook URL to https://<api-origin>/integrations/github/webhooks,
3. install the app on skeehn/documint,
4. sync the installation repo catalog in /app/onboarding,
5. let webhook deliveries trigger repo-backed drift checks,
6. review the findings and proposed patch before opening or merging a docs PR.

Auth and operator flow

• Production /app routes are protected with Clerk when Clerk is configured.
• The backend accepts three credential types:
  • service bearer token for internal bootstrap/admin flows
  • hashed workspace API tokens for CLI and MCP
  • Clerk JWTs for the operator app
• Production operator pages no longer render fake project state when the backend is unavailable. They render a degraded unavailable state instead.

Local full-stack options

• npm run dogfood is the fastest end-to-end local smoke test.
• docker compose up --build runs the repo-native stack with web, api, and redis.
• docker compose -f docker/docker-compose.dev.yml up --build provides the same stack from the legacy docker/ entrypoint, now aligned with V1.