Javelin Documentation Structure

This is a proposed new structure for the Javelin documentation.

The new Javelin documentation structure focuses on clarity, flow, and practical guidance. It opens with a concise yet engaging overview that quickly communicates what makes Javelin unique. From there, content is organized into clear sections—from installation and core concepts to step-by-step guides and advanced topics. This structure lowers the barrier to entry, speeds up onboarding, and makes it easier for both newcomers and experienced developers to find exactly what they need.

Some sections can reuse existing content with improved organization and clearer headings. Others will need to be newly written based on the functionality available in the codebase and examples from the Javelin GitHub repository. Where content is not yet available, these sections are marked with TODO.

1. Introduction

• What is Javelin?
• Technical Overview
• TODO: Quickstart for Organization Manager
• TODO: Quickstart for Developer

2. Tutorials

• Isolated tutorials on how to use each feature
• There can be many of them: secrets, filter tracing by apps, setup various policies

3. Core Concepts

• Processor Chains
  • Request & Response Chains
  • Sync vs. Async Execution
• Guardrails & Policies
• Universal Endpoints
• Streaming Capabilities
• Caching & Performance Optimization
• Data Protection Templates

4. Advanced Capabilities

• TODO: Model Transformation Rules
• TODO: High Availability & Fallbacks
• TODO: Cost Control & Budgeting
• TODO: Observability & Monitoring

5. Developer Tooling

• CLI Usage & Examples
• Debugging Requests
• Local Development Best Practices

6. Integration Guides

• Python SDK
• REST API
• Provider Integrations
  • OpenAI
  • Anthropic Claude
  • Google Gemini
  • Mistral
  • HuggingFace
• TODO: Agent Integrations

7. Architecture

• System Overview
• Component Diagrams
• Data Flow Explanation

8. Examples

• TODO: Chat Completion Chain
• TODO: Secure Data Redaction
• TODO: Multi-provider Failover

9. FAQs & Troubleshooting

• Common Issues
• Known Limitations

---

Additional Recommendations

1. Remove the homepage landing screen.
   The documentation should open directly to usable content (e.g. Getting Started), not a marketing-style homepage.

2. Add a favicon.
   A branded favicon should be added to help identify the docs tab in browser UIs.

3. Enable search functionality.
   Search should be available across all documentation pages for easier navigation.

4. Move the Python SDK API reference to a separate site.
   Generate a dedicated site for the SDK API reference using Sphinx or similar tools, as is standard for Python packages.

5. Host changelog on GitHub.
   Reference the GitHub CHANGELOG.md file in the docs instead of embedding a changelog directly.

6. Add a Contact & Feature Access section.
   Provide guidance on how to request access to closed features, report bugs, or suggest enhancements (e.g., GitHub Issues or Discussions).

7. Reference GitHub examples more frequently.
   Add inline links to Javelin GitHub repo throughout the docs, especially in integration and examples sections.

8. Link to API Reference from UI doesn't work

   • /docs/javelin-python/models -> /javelin-python/models
   • /docs/javelin-core/overview -> /

---

Sample Article (setting up Javelin gateway with provider, route, fallbacks, guardrails and data protection)

If I were a developer using Javelin for the first time, my journey would likely follow these steps.

1. Authentication and Setup

javelin auth

This starts a web-based authentication flow that:

• Starts a local web server
• Opens a browser for authentication
• Stores credentials in ~/.javelin/cache.json

2. Setting Up a Gateway

javelin gateway create --name "my-gateway" --type "production" --enabled true --config '{"base_url": "https://api.javelin.live", "api_key": "your_api_key"}'

Or programmatically:

from javelin_sdk import JavelinClient, JavelinConfig, Gateway, GatewayConfig

client = JavelinClient(JavelinConfig(javelin_api_key="your_api_key"))
gateway = Gateway(
    name="production-gateway",
    type="production",
    config=GatewayConfig(
        base_url="https://api.javelin.live",
        api_key="your_api_key"
    )
)
client.gateway_service.create_gateway(gateway)

3. Creating a Provider

javelin provider create --name "openai-provider" --type "openai" --enabled true --vault_enabled true --config '{"api_key_secret_name": "openai-key"}'

Or programmatically:

from javelin_sdk import Provider, ProviderConfig

provider = Provider(
    name="openai-provider",
    type="openai",
    enabled=True,
    vault_enabled=True,
    config=ProviderConfig(api_key_secret_name="openai-key")
)
client.provider_service.create_provider(provider)

4. Setting Up API Keys (Secrets)

javelin secret create   --api_key "openai-key"   --api_key_secret_name "OpenAI API Key"   --api_key_secret_key "sk-..."   --provider_name "openai-provider"   --header_key "Authorization"

5. Creating Routes

javelin route create --name "chat-completion" --type "chat" --enabled true --models '[{"name": "gpt-4", "provider": "openai-provider"}]' --config '{}'

Or programmatically:

from javelin_sdk import Route, Model, RouteConfig

route = Route(
    name="my-gpt-route",
    type="chat",
    models=[
        Model(name="gpt-4", provider="openai-provider")
    ],
    config=RouteConfig(
        rate_limit=100,
        llm_cache=False
    )
)
client.route_service.create_route(route)

6. High Availability & Fallbacks

route = Route(
    name="my-fallback-route",
    type="chat",
    models=[
        Model(
            name="gpt-4",
            provider="openai-provider",
            fallback_enabled=True,
            fallback_codes=[429, 500, 503]
        ),
        Model(
            name="claude-2",
            provider="anthropic"
        )
    ]
)
client.route_service.create_route(route)

7. Guardrails

result = client.guardrails_service.apply_guardrails(
    text="User input here",
    guardrails=[
        {"name": "trustsafety", "config": {"threshold": 0.7}},
        {"name": "promptinjectiondetection", "config": {"threshold": 0.5}}
    ]
)

8. Data Protection Templates

javelin template create --name "pii-mask" --description "Masks PII data" --type "redaction" --enabled true --config '{"redaction_type": "pii"}'

9. Making LLM Requests

response = client.route_service.query_route(
    route_name="my-gpt-route",
    query_body={
        "messages": [
            {"role": "user", "content": "Hello, how are you?"}
        ]
    }
)