AI-friendly document collaboration hub with OpenAPI docs, Markdown docs, semantic diff, and MCP.
Vdoc helps AI/vibe-coding teams keep API changes, Markdown project knowledge, frontend integration work, and AI agent context in sync.
Vdoc is a document collaboration platform for fast-moving teams. A Project owns typed Documents, including OpenAPI API docs and Markdown docs. Vdoc stores every published document as an immutable version, computes OpenAPI semantic diffs or Markdown text diffs, and exposes reviewed document knowledge to both humans and AI agents.
The long-term goal is not to build another Swagger UI clone. Vdoc focuses on the workflow that often breaks in AI-assisted development:
Backend uploads or AI submits an OpenAPI or Markdown draft through MCP
-> A human reviewer approves it and Vdoc creates an immutable version
-> Vdoc parses OpenAPI endpoints when applicable
-> Vdoc computes OpenAPI semantic diff or Markdown text diff
-> Vdoc marks breaking changes when applicable
-> Frontend or AI queries changes, endpoint details, or Markdown content
-> Frontend updates integration code and project knowledge with context
This repository contains the Go/Gin backend for Vdoc v0.1.
API documentation:
- Human-readable guide: docs/api/API.md
- Machine-readable OpenAPI spec: docs/api/openapi.yaml
- Reviewed upstream scaffold delta: docs/scaffold-sync.md
Public workspace deployment and release documents are maintained in Vdoc-site:
First download and initialize the full workspace. The backend repository alone does not contain the root Compose files. Run the following from the initialized workspace root:
scripts/vdoc-local-bootstrap.sh
docker compose --env-file .env up -d --build
cd Vdoc && go run ./tools/vdoc-demo-seedThe demo seed is optional. For live E2E, keep the root Compose stack running and use the backend script:
cd Vdoc
./scripts/vdoc-e2e.sh live-compose --env-file ../.env --check-only
./scripts/vdoc-e2e.sh live-compose --env-file ../.envLive E2E resets the selected disposable VDOC_TEST_POSTGRES_DB, vdoc_e2e by default. It does not use or reset the application database from VDOC_POSTGRES_DB. Use the release dry-run as the local gate:
scripts/vdoc-release-dry-run.sh --list
scripts/vdoc-release-dry-run.shDo not commit .env or expose raw JWTs, MCP tokens, DB passwords, storage secrets, or Authorization header values.
Implemented in v0.1:
- Versioned route tree under
/api/v1 - Public login, opt-in registration, and private JWT routes
- SuperAdmin user lifecycle, teams, projects, members, documents, and document branches
- OpenAPI and Markdown draft upload, review, and immutable version publishing
- Raw, normalized, and stable content retrieval for drafts and published versions
- Endpoint index queries, semantic OpenAPI diff summaries, and Markdown file diffs
- MCP token lifecycle and JSON-RPC MCP read and draft tools
- Admin API support for product onboarding, workflow guidance, developer-portal endpoint browsing, document content, and diff review
- Unified JSON response envelope with
trace_idandtimestamp - Request tracing, structured access logs, panic recovery, CORS, security headers, body-size limit, and rate-limit middleware
- Viper-based configuration with
VDOC_environment variables - Makefile targets for build, test, lint, format, and cross-platform packaging
Not in v0.1:
- Direct MCP publish tools
- Code generation and frontend integration helpers
- Commercial operations features such as billing, notification center, integration marketplace, and organization-level tenant administration
Push a version tag such as v0.1.1 or v0.1.1-rc.1 after committing the release changes. Backend CI runs its existing tests, PostgreSQL integration gate, and E2E smoke before packaging Linux amd64/arm64, macOS amd64/arm64, and Windows amd64 binaries. The archives include the license, configuration example, and documentation, with SHA256SUMS for verification. Version, full Git commit, and commit time are embedded in the binaries.
CI uploads the verified artifacts and then creates a GitHub Release from the existing tag. Prerelease tags create prereleases. Ordinary branch pushes and pull requests run checks only. The publish job reuses the verified artifacts and does not overwrite an existing release.
For a local packaging check, run make release-package RELEASE_TAG=v0.1.0 with the intended version; output stays in the ignored dist/ directory. After component releases, update the workspace lock before publishing a Site/Compose release that selects those versions.
| Concept | Meaning |
|---|---|
| Team | A collaboration boundary for people and projects. |
| Project | A product or app owned by a team. |
| Document | A typed project document. v0.1 supports OpenAPI API docs and Markdown docs. |
| Document Type | 1 means OpenAPI. 2 means Markdown. |
| Relative Path | The project-local path identity for a document, such as apis/petstore.yaml or docs/runbook.md. |
| Document Branch / Environment | A Vdoc document track, such as dev, test, prod, or feature/*. prod is protected by default. |
| Document Version | An immutable snapshot for one typed document. |
| Endpoint Index | A structured database index of paths, methods, parameters, request bodies, responses, tags, and operation IDs. |
| Semantic Diff | Contract-aware comparison between two versions, not raw text diff. |
| Breaking Change | A change that can break frontend consumers, such as field removal, type change, new required parameter, or endpoint removal. |
| MCP Token | A user-bound AI tool token. Creation returns a copyable value; its owner may reveal it again while active, while list/revoked/expired responses are redacted. Effective permissions come from token scopes plus the user's role on the target project. |
- SuperAdmin creates system members, teams, and projects.
- SuperAdmin assigns the initial Project Admin.
- Project Admin manually adds existing system users and assigns project-level roles.
- Project Admin creates an OpenAPI or Markdown Document with a
relative_path. - Writer uploads through Web API, or AI submits a draft through MCP for a target document branch.
- Vdoc validates and stores raw content plus normalized or stable snapshots.
- Project Admin approves the draft and Vdoc creates an immutable document version.
- Vdoc parses an endpoint index for OpenAPI documents.
- Vdoc compares the new version with the previous one using OpenAPI semantic diff or Markdown text diff.
- Vdoc stores a change summary and breaking-change list when applicable.
- Frontend developers and AI agents query endpoint details, Markdown content, diffs, and summaries.
Implemented in the current v0.1 backend:
- System-level
SuperAdmin; project-level roles:Reader,Writer,Admin, where Writer submits drafts and Admin reviews/publishes them - OpenAPI 3.x and Markdown upload through Web API, plus MCP draft submission and updates
- Manual project member adds from existing system users, without invitation workflow in MVP
- Document branches/environments with
dev,test, protectedprod, optionalfeature/*, and promote-to-target-draft flow - Immutable versions per typed document
- Human-reviewed publication for OpenAPI and Markdown drafts
- Endpoint list and endpoint detail query
- Version comparison with semantic OpenAPI diff or Markdown file diff
- Breaking-change summary
- MCP read and draft tools only; human review publishes versions
Explicitly out of scope for the first MVP:
- Complex organization-wide RBAC
- GraphQL, gRPC, Postman, YApi, or Apifox import
- Full SDK generation platform
- Automatic modification of frontend repositories
- Complex multi-step approval workflows
Read tools:
list_projects
list_documents
list_document_branches
list_api_endpoints
list_api_versions
list_doc_versions
get_latest_schema
get_endpoint_detail
compare_api_versions
get_change_summary
get_latest_doc
compare_doc_versions
Draft tools for v0.1:
create_api_version_draft
update_api_version_draft
submit_api_version_draft
get_api_version_draft
create_doc_draft
update_doc_draft
submit_doc_draft
get_doc_draft
Direct publish tools are not available in v0.1. Human Admin or SuperAdmin review publishes versions.
Installable agent-facing assets are kept outside this backend repository: the MCP stdio adapter lives in Vdoc-mcp, and the workflow skill lives in Vdoc-skill.
Web App
- Team / project / member / role management
- API documentation view
- Version list
- Semantic diff view
- Breaking-change summary
API Server
- Project management
- Document and document branch management
- OpenAPI and Markdown upload
- Draft review and publication
- Document version creation
- Permission checks
- Diff query
- MCP token management
MCP Server
- AI OpenAPI and Markdown document lookup
- AI version diff lookup
- AI OpenAPI and Markdown draft submit/update
- AI frontend change summaries
Diff Engine
- OpenAPI parse
- Schema normalization
- Contract model extraction
- Semantic diff
- Breaking-change rules
Storage
- PostgreSQL for users, teams, projects, documents, branches, drafts, versions, endpoint indexes, diff summaries, audit logs, and token security metadata
- RustFS or any S3-compatible object storage for raw, normalized, stable, and large diff snapshots when `storage.enabled=true`
- In-memory compatibility store for local development and tests when `database.enabled=false`
vdoc/
├── main.go # Server lifecycle, CLI flags, config, logging, graceful shutdown
├── Makefile # Build, run, test, format, lint, verify
├── api/ # Transport layer: Gin routes, middleware, request/response DTOs, error mapping
├── common/ # Shared business semantics: enums, constants, DTOs used across modules, events
├── config/ # Viper config loading, defaults, restart validation, safety checks
├── db/ # Persistence adapters: GORM/PostgreSQL models, queries, migrations, RustFS/S3 adapters
├── domain/ # Business rules, state transitions, domain errors, repository and storage ports
├── services/ # Long running cron, worker, and consumer lifecycle tasks
├── static/ # Static asset placeholder
└── utils/ # Business neutral infrastructure helpers for JWT, logging, IDs, crypto, paths
- Go 1.25+
- Make
cp config.yaml.example config.yamlSet a strong JWT key before running the service:
export VDOC_JWT_KEY="$(openssl rand -base64 32)"You can also edit config.yaml directly. Do not commit real config.yaml files or secrets.
make devHealth check:
curl http://127.0.0.1:8080/api/v1/open/healthBuild the backend image from this repository root:
docker build -t vdoc-backend:local .Run with environment-only configuration. Production runs must provide real secrets and external dependency endpoints; do not use localhost for services in other containers.
docker run --rm -p 8080:8080 \
-e VDOC_JWT_KEY="$(openssl rand -base64 32)" \
-e VDOC_SERVER_PORT=8080 \
vdoc-backend:localThe image exposes port 8080, runs as a non-root user, and includes a healthcheck for /api/v1/open/health. Workspace Compose guidance lives in COMPOSE_DEPLOY.md.
make help
make build
make run
make dev
make test
make test-coverage
make fmt
make fmt-check
make lint
make build-check
make verify
make clean
make build CROSS=1The full v0.1 route list is maintained in docs/api/API.md and docs/api/openapi.yaml. The implemented surfaces include public health/auth/docs/MCP routes and private identity, user, team, project, member, document, branch, draft, version, endpoint, diff, and MCP token routes.
Responses use a project envelope. HTTP status is currently always 200; semantic success or failure is represented by the JSON code and status fields.
Configuration is loaded from config.yaml, defaults, and VDOC_ environment variables. The backend process does not auto-load .env; export variables through the shell or process manager. In the supported workspace deployment, root Docker Compose reads the root .env file.
server.host defaults to 0.0.0.0; use 127.0.0.1 for direct local-only access. server.static_dir defaults to ./static relative to the working directory and can be set to an empty string to disable /static. Native process-manager deployments may set VDOC_SERVER_PID_FILE explicitly; the Docker image and supported Compose stack set it to an empty value because Docker owns process supervision. This prevents an OOM or SIGKILL from leaving a writable-layer PID file that blocks the container restart policy.
Examples:
export VDOC_SERVER_HOST=127.0.0.1
export VDOC_SERVER_PORT=9090
export VDOC_JWT_KEY="$(openssl rand -base64 32)"
export VDOC_LOG_LEVEL=info
export VDOC_AUTH_ALLOW_REGISTRATION=false
export VDOC_INITIAL_ADMIN_EMAIL="admin@example.com"
export VDOC_INITIAL_ADMIN_NAME="Vdoc Admin"
export VDOC_INITIAL_ADMIN_PASSWORD="<initial-admin-password>"
export VDOC_DATABASE_ENABLED=true
export VDOC_DATABASE_DSN="postgres://vdoc:<password>@127.0.0.1:5432/vdoc?sslmode=disable"
export VDOC_STORAGE_ENABLED=true
export VDOC_STORAGE_ENDPOINT="127.0.0.1:9000"
export VDOC_STORAGE_BUCKET="vdoc"
export VDOC_STORAGE_ACCESS_KEY="<access-key>"
export VDOC_STORAGE_SECRET_KEY="<secret-key>"
export VDOC_MCP_TOKEN_CIPHER_KEY="<independent-key-at-least-32-characters>"
export VDOC_MCP_TOKEN_CIPHER_KID="local-aes-gcm-v1"
export VDOC_MCP_TOKEN_CIPHER_KEYRING='{}'Anonymous HTTP registration is disabled by default. Keep auth.allow_registration=false in production and configure initial_admin.email plus initial_admin.password for a fresh deployment. Registration may be explicitly enabled only for a trusted disposable or pilot environment with VDOC_AUTH_ALLOW_REGISTRATION=true; while enabled, any network caller can create an active account. The initial admin is created only when the loaded user table is empty, and its password is bcrypt-hashed before persistence. When database.enabled=true, Vdoc connects to PostgreSQL during startup, creates its runtime tables, and loads existing state. Connection or migration failure aborts startup instead of silently falling back to memory. When storage.enabled=true, raw and normalized OpenAPI schemas are written to RustFS or any S3-compatible object storage; the bucket is created automatically when missing.
The cipher KID is a key identity, not an algorithm switch: never reuse a KID
with different key material. During rotation, set a new active KID/key and put
the old KID/key in the JSON mcp_token.cipher_keyring. Startup validates and
transactionally re-encrypts MCP token, AI Provider, and public-share ciphertext
to the active KID. Remove the historical keyring only after the database shows
no old KIDs; the full procedure is in RELEASE_DEPLOY.md.
Register and login always have an independent per-IP limiter, configured by auth.rate_limit and auth.rate_burst, even when the optional global server limiter is disabled.
If a SuperAdmin password is lost, run the built binary against the configured PostgreSQL database without starting the HTTP server:
set +x
read -r -s NEW_PASSWORD
printf '%s\n' "$NEW_PASSWORD" | ./vdoc --resetadmin admin@example.com
unset NEW_PASSWORDThe password is read from standard input so it does not appear in shell history or the process argument list. The target user must already exist, be active, and be a SuperAdmin. The new password follows the same strength rule as initial_admin.password.
Config file lookup order:
- Working directory
/etc/vdoc/
Issues and pull requests are welcome. Since the project is early, please keep changes aligned with the MVP scope: OpenAPI and Markdown documents, immutable versions, endpoint indexes, semantic diff, Markdown diff, and MCP integration.