# CBB Project Brief: .dope SDK — Open Source Developer Library
**Status:** Concept
**Destination:** ScopeDOPE feature (the `.dope` format is the ScopeDOPE product's open format; SDK work belongs with the format/`dope-format` repo in the `ScopeDOPE/` namespace)
**Tier:** 1 — Highest Strategic Priority
**Classification:** Internal — Confidential
**Version and date:** see Revision Control Block at the end of this document

---

## Summary

A reference implementation library for reading, writing, and validating the .dope file format, published as open source in Python, Swift, and Kotlin. Any developer building a ballistic, reloading, or shooting sports app can integrate .dope format compatibility in an afternoon instead of reading a specification document and implementing it from scratch. Cold Bore Ballistics™ maintains the library and the spec. This is the strategic mechanism that transforms the .dope format from a feature of ScopeDOPE™ into an industry standard — and makes Cold Bore Ballistics the steward of that standard. The SDK is the highest-leverage acquisition value multiplier in the entire CBB project portfolio relative to its development cost.

---

## Problem Statement

The .dope format was designed as an open specification to enable interoperability across ballistic tools. Publishing the spec alone is necessary but insufficient for adoption. Most developers building competing or complementary apps will not invest significant time implementing the format from a specification document unless:
1. The format already has traction they can't ignore
2. Implementation is nearly free (i.e., a library exists)

The SDK eliminates barrier #2 entirely. A developer who spends 30 minutes integrating a library becomes part of the .dope ecosystem. A developer who has to implement a spec from scratch might spend a week — most won't bother. The SDK is the difference between a format that gets adopted and one that doesn't.

---

## Strategic Context

The .dope format is licensed under a Custom Open Specification License:
- Free to implement, royalty-free, forever
- Attribution to Cold Bore Ballistics LLC required in implementations
- Cold Bore Ballistics is the sole authoritative version publisher
- The "Certified .dope Compatible" certification mark (targeted for ~5,000 installs) requires formal certification from CBB

The SDK is the technical foundation for the certification program. A library that is the reference implementation means any certified implementation is measured against CBB's SDK. This is how CBB retains stewardship even as the format becomes widely adopted.

---

## Product Concept

### SDK Components

**Core Libraries (all three languages on day one)**

`dope-python` — Python library
- Primary use: server-side processing, data science, backend integrations
- Target users: developers building web services, data pipelines, ammo manufacturer integrations
- Install: `pip install dope-ballistics`
- License: MIT

`dope-swift` — Swift library
- Primary use: iOS app integration
- Target users: iOS developers building competing or complementary apps
- Install: Swift Package Manager
- License: MIT

`dope-kotlin` — Kotlin library
- Primary use: Android app integration
- Target users: Android developers
- Install: Gradle
- License: MIT

**Features in all three libraries:**
- Read .dope files (parse JSON structure, validate schema, return typed objects)
- Write .dope files (serialize typed objects to valid .dope JSON)
- Validate .dope files (check spec compliance, return errors for invalid files)
- Diff two .dope sessions (identify what changed between versions)
- Merge two .dope sessions (combine sessions from different devices)
- Version detection (handle .dope v1.0, v1.1, etc. transparently)

**Companion tooling:**

`dope-cli` — Command-line tool (Python-based)
- `dope validate <file>` — validate a .dope file against the spec
- `dope inspect <file>` — print human-readable summary of a .dope session
- `dope convert <file> --format json/csv` — export to other formats
- `dope merge <file1> <file2>` — merge two sessions
- Install: `pip install dope-ballistics[cli]`

**Developer portal:** `docs.coldboreballisticsllc.com/dope-sdk`
- Getting started guide
- API reference for all three libraries
- Example implementations
- Changelog
- Certification program documentation (when ready)

---

## Target Developer

**Competing app developers:** Other ballistic calculator apps that want .dope import/export without building it themselves. Even competitors benefit from format compatibility — a user who exports from ScopeDOPE should be able to import into any certified app. This builds user trust in the ecosystem.

**Complementary app developers:** Reloading apps (Cold Bore Load's competitors), club management apps, coaching tools, match scoring software — any app that might want to read or write ballistic session data.

**Hardware manufacturers:** Scope manufacturers building companion apps (Apex Optics, Arken, Tract — see OPTICS_PARTNERSHIP_TARGETS.md). An optics partner who wants to show ScopeDOPE session data in their own app uses the SDK.

**Ammo manufacturers:** Companies building ballistic tools as a value-add for their customers. ELEY, SK, Lapua — any manufacturer who wants to show lot-specific ballistic data in a .dope-compatible format.

**Researchers and data analysts:** Graduate students, applied ballistics researchers who want to work with real-world field data. The Python library is the right tool for this use case.

---

## Revenue Model

**Direct revenue: None.** The SDK is free and open source (MIT license).

**Indirect revenue:**
- **Adoption flywheel:** Every app that integrates the SDK is a funnel to ScopeDOPE. A user who exports a .dope file from a competing app and opens it in ScopeDOPE becomes a CBB user. The SDK is a conversion channel disguised as a developer tool.
- **Certification revenue:** "Certified .dope Compatible" mark (~$350 USPTO certification trademark, targeted at ~5,000 installs). Apps that want the certification badge pay for the certification process. This is a recurring annual certification fee — nominal per app but meaningful at volume.
- **Acquisition value multiplier:** Being the steward of an adopted open standard is a fundamentally different acquisition profile than being an app company. Garmin's GPX format, Strava's FIT format — the steward has durable moat value that no competitor can replicate by copying the app.

---

## Strategic Fit with CBB / ScopeDOPE

The SDK is the strategic mechanism that makes the .dope format real. Without it, the format is a specification document that no one implements. With it:

1. **Other apps implement .dope** because it's nearly free to do so
2. **ScopeDOPE becomes the reference implementation** — if your app generates .dope files that don't open correctly in ScopeDOPE, your implementation is wrong by definition
3. **CBB owns the certification** — apps that want the "Certified .dope Compatible" badge go through CBB
4. **The format ecosystem amplifies ScopeDOPE** — every .dope-compatible app is a potential ScopeDOPE feeder
5. **Acquisition value ceiling rises** — an acquirer buying CBB gets the standard, the stewardship, and the certification program, not just the app

This is the highest-ceiling strategic asset in the CBB portfolio. It is also the lowest-cost asset to build — the spec is already written, and the SDK is an implementation of that spec.

---

## Competitive Landscape

No comparable open standard exists for precision rifle ballistic data. Applied Ballistics has a proprietary format used by Kestrel devices. Hornady has a proprietary format. Neither publishes an SDK. Neither has an open certification program. The .dope format fills a genuine gap that no existing player is positioned to fill.

---

## Technical Overview

**Implementation approach:**
- Python library first (fastest to write, most useful for initial developer testing and data science)
- Kotlin library second (ScopeDOPE's Android codebase is Kotlin — the library is derived from ScopeDOPE's own internal .dope handling code)
- Swift library third (derived from ScopeDOPE's iOS .dope handling code)

**Key engineering principle:** The SDK libraries should be generated from or tightly synchronized with ScopeDOPE's own .dope handling code. If ScopeDOPE can read a .dope file, the SDK should be able to read the same file identically. Don't maintain two separate implementations.

**Distribution:**
- PyPI: `pip install dope-ballistics`
- Swift Package Manager: `https://github.com/coldboreballisticsllc/dope-swift` *(confirm the actual GitHub org slug before publishing)*
- Maven Central / JitPack: `com.coldboreballistics:dope-kotlin`

**Documentation:** `docs.coldboreballisticsllc.com` (static site, MkDocs or Docusaurus)

**CI/CD:** GitHub Actions — automated tests on every commit, automated publish to package registries on tag

**Complexity estimate:** Low-Medium. The spec is already written. The SDK is an implementation of a known format. The Python library is a weekend project. Kotlin and Swift add another week each. The CLI tool is an afternoon. The developer portal is another few days. Total: 3–4 weeks for complete initial SDK.

---

## Go-to-Market

**Phase 1 — Publish and announce:**
- Publish all three libraries to their respective registries
- Announce on Sniper's Hide developer forum and precision shooting subreddits
- Post on Hacker News (Show HN) and relevant developer communities
- Submit to shooters-focused developer forums (there are small but active communities)

**Phase 2 — Partner outreach:**
- Contact every optics partner in OPTICS_PARTNERSHIP_TARGETS.md with "If you're building a companion app, here's how to make it .dope compatible in a day"
- Contact ammo manufacturers building ballistic tools (ELEY, SK)
- Approach PRS and NRL22 scoring app developers

**Phase 3 — Certification program (at ~5,000 installs):**
- Launch "Certified .dope Compatible" program
- First certifications: ScopeDOPE (obviously), Cold Bore Load (Brief #01)
- Annual certification renewal at nominal fee

---

## Success Metrics

| Metric | 6-month | 12-month | 24-month |
|---|---|---|---|
| GitHub stars (Python lib) | 50 | 200 | 500 |
| PyPI downloads/month | 100 | 500 | 2,000 |
| Apps implementing .dope format | 2 | 5 | 15 |
| Certified .dope Compatible apps | — | — | 5 |
| Developer portal unique visitors/month | 50 | 300 | 1,000 |

---

## Risks & Mitigations

| Risk | Likelihood | Mitigation |
|---|---|---|
| Format not adopted — not enough developers in this niche | Medium | The niche is small but the SDK lowers the barrier to nearly zero; even 3–4 apps adopting the format is sufficient for strategic value |
| Applied Ballistics publishes a competing open format | Low | AB's business model depends on proprietary hardware integration; open formats undermine their model |
| SDK diverges from ScopeDOPE internal format handling | Medium | Strict CI/CD policy: SDK tests must pass against ScopeDOPE-generated .dope files |
| Spec version proliferation — multiple incompatible .dope versions | Medium | Strict versioning policy documented in the spec; SDK handles all published versions transparently |

---

## Resource Requirements

- 1 developer (Jason) — 3–4 weeks for all three libraries plus CLI and documentation
- GitHub organization: the CBB org (confirm exact slug; align to `coldboreballisticsllc`, not the unowned `coldboreballistics`)
- PyPI, SwiftPM, JitPack accounts: free
- Documentation hosting: Azure Static Web Apps (consistent with existing CBB website infrastructure)

---

## Recommended Timing

**Build in parallel with ScopeDOPE v1.0.** The SDK is derived from ScopeDOPE's internal .dope handling code. Writing the SDK while writing the ScopeDOPE .dope implementation ensures they stay synchronized and eliminates the future work of extracting/adapting the internal code into a library. The SDK can be published as a "preview" simultaneously with ScopeDOPE launch, and v1.0 can follow within weeks.

---

## Open Questions

- Should the SDK be published under CBB's GitHub organization or a neutral organization name (e.g., a `dope-format` org)? Recommendation: start under CBB's GitHub org for credibility and control; consider a neutral home if adoption warrants. *(Confirm the exact org slug — align to the owned `coldboreballisticsllc` convention, not the unowned `coldboreballistics`.)*
- What is the minimum .dope spec version to support at SDK v1.0? Recommendation: .dope v1.0 only; add version compatibility as spec evolves.
- Should the CLI include a ballistic solver (i.e., generate a predicted DOPE table from a .dope file's inputs)? Recommendation: no — the CLI is a format tool, not a ballistic calculator. Keeping these separate maintains the format's neutrality.

---

## Document Control

| Field | Value |
|---|---|
| **Document owner** | `jschwefel@coldboreballisticsllc.com` |
| **Classification** | Confidential (03_-_Confidential/) |
| **Location** | `OneDrive/ScopeDOPE/03_-_Confidential/Product_Strategy/CBB_BRIEF_06_DOPE_SDK.md` |
| **Cross-references** | `CBB_PROJECT_BRIEFS_TOC.md` |
| **Created** | 2026-06-02 |
| **Last updated** | 2026-06-09 |
| **Next full review due** | 2027-06-02 |

---

## Revision Control Block

| Rev | Date | Changed By | Reviewed By | Approved By | Summary |
|-----|------|------------|-------------|-------------|-------|
| 0.9 | 2026-06-02 | jschwefel | — | — | Initial release |
| DRAFT | 2026-06-09 | Claude (Opus 4.8) | — | — | Removed header version number (→ Status/Destination + revision-block pointer); added Destination tag (ScopeDOPE feature). Replaced forbidden `docs.coldboreballistics.com` (×2) → `docs.coldboreballisticsllc.com`; replaced Cloudflare Pages → Azure Static Web Apps; flagged `github.com/coldboreballistics` org slug to align to the owned `coldboreballisticsllc` (verify before publishing). Applied ™ to first use of ScopeDOPE/Cold Bore Ballistics. |
