page:blueprints:developer tools:documentation site:django

Developer tools: documentation site using Django

Summary A documentation site blueprint for developer tools built with Django on Ample. Domain schema:

• customer_workspaces (name, plan, api_key_count): customer organizations;
• doc_versions (product_version, title, object_key, published_at): versioned reference docs and guides;
• sdk_releases (language, version, changelog_object_key, released_at): SDK releases and changelogs;
• customer_assets (workspace_id, title, object_key, visibility): customer-specific artifacts;
• state_transitions (record_type, from_state, to_state): the allowed state machine. Public information includes versioned API references and guides, SDK release notes, and status page links.

Kept out of scope until handling is reviewed: customer API keys and usage logs, private integration details. API keys and usage logs are secrets or personal data and should be kept out of documentation workflows.

Technical basis verified on Django: a workspace-scoped table, an explicit state machine (draft to review to published) that rejects invalid transitions, and a cross-workspace read that returns nothing (transitions=true isolation=true).

Resource Requirements

• Compute: Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.
• Postgres: Managed PostgreSQL 16 runs in its own microVM and is auto-provisioned when an app needs a database and no DATABASE_URL is supplied.
• CDN: The CDN host serves objects from published buckets without caching or acting as a key-value store.

Prerequisites

1. A Django project (pip install into .ample/python from requirements.txt, then waitress serving project.wsgi from run.py reading PORT on the python-3.12 template)
2. A PostgreSQL driver reading DATABASE_URL (auto-provisioned when omitted)
3. Bucket credentials from ample bucket create passed as encrypted S3_* environment variables and a published bucket for public assets (CDN_*)
4. A review of which developer tools data classes may be handled at all; this blueprint models public information only.

Workflow Steps

1. Model the developer tools domain: Create the tables customer_workspaces, doc_versions, sdk_releases, customer_assets, state_transitions. Sensitive classes (customer API keys and usage logs, private integration details) should be kept out of this schema.
2. Model versioned documents with a state machine (draft, review, published) scoped to a product version.
3. Publish assets for released versions to the CDN bucket.
4. Serve only published versions publicly.
5. Deploy and verify the version list and a published page.
6. Verify functionality by running the appropriate self-tests and acceptance checks for the developer tools workflow.

Cost Estimate

• Monthly amount: $10.00 USD
• Basis: size prices from pricing.toml (loaded by the API)
• Components:
  • App server: 1 x s-1vcpu-1gb = $5.00
  • Managed PostgreSQL database: 1 x s-1vcpu-1gb = $5.00

Limitations

• The developer tools schema and workflow were an original design for this blueprint and were not executed as a separate application. General compliance and other operational claims are not made.

Success Checks

• App responds on its public URL (expecting the canary django patterns).
• Relational-records self-test from the example (expecting to see the pattern fixture checks).

Examples

• Django pattern fixture: Verified relational records basis for this blueprint.

Next Actions

• Browse the catalog index
• Search published recipes by intent, stack and constraints
• Prepare a side-effect-free deployment plan for an authorized project.
• Read the existing agent authentication setup.
• Browse various nodes in the developer tools industry.