# Atlassian Architecture Reference

# Cold Bore Ballistics, LLC

**Last updated:** 2026-06-10
**Status:** As-built — reflects the live instance
**Site:** `coldboreballisticsllc.atlassian.net`
**Products:** Jira Software · Jira Service Management · Confluence (all Free tier)

> **Purpose of this document.** This is the authoritative "as-built" record of the
> Atlassian instance — what exists, how it is configured, and why. It is written for
> a reader with **no prior exposure to this instance or to Atlassian Cloud** — for
> example, an acquiring company's engineering team operating the system without the
> founder present. It supersedes the pre-implementation `Atlassian_Configuration_Plan.md`.
>
> Two companion documents accompany this one:
> - **`Atlassian_Operating_Runbook.md`** — how to perform recurring tasks (add a user,
>   triage a ticket, run a release in Jira, manage the support queue).
> - **`Atlassian_Rebuild_Guide.md`** — how to reproduce the entire instance from scratch
>   (scripts plus every manual step) for disaster recovery or due-diligence handoff.

---

## Table of Contents

1. [Orientation — what Atlassian Cloud is](#1-orientation--what-atlassian-cloud-is)
2. [Site and Plan](#2-site-and-plan)
3. [Identity, Groups, and Permissions](#3-identity-groups-and-permissions)
4. [Jira Project: DOPE (product)](#4-jira-project-dope-product)
5. [Jira Project: CBB (operations)](#5-jira-project-cbb-operations)
6. [Jira Service Management: ESUP (support)](#6-jira-service-management-esup-support)
7. [Resolutions](#7-resolutions)
8. [Custom Fields](#8-custom-fields)
9. [Confluence Spaces](#9-confluence-spaces)
10. [GitHub for Jira Integration](#10-github-for-jira-integration)
11. [Issue Tracking Policy](#11-issue-tracking-policy)
12. [Free-Plan Limitations (as-built constraints)](#12-free-plan-limitations-as-built-constraints)
13. [Credentials](#13-credentials)
14. [Reference IDs](#14-reference-ids)

---

## 1. Orientation — what Atlassian Cloud is

If you have never used Atlassian before, read this section first. The rest of the
document assumes the vocabulary defined here.

- **Atlassian** is a vendor. It hosts a family of web applications. Cold Bore Ballistics
  uses three of them, all under one web address ("**site**"): `coldboreballisticsllc.atlassian.net`.
- **Jira Software** — issue tracking for software development. Work is recorded as
  **issues** (a bug, a task, a feature). Issues live inside a **project**. A project has
  a **board** (a visual column layout: To Do → In Progress → Done).
- **Jira Service Management (JSM)** — a help-desk variant of Jira. People outside the
  team submit **requests** through a **portal** (a public web form). Internally, those
  requests are just Jira issues handled by **agents**.
- **Confluence** — a wiki. Pages of documentation organized into **spaces**.
- **Groups** — named buckets of users (e.g. `jira-admins`). Permissions are granted to
  groups, not to individuals, so access is managed in one place.
- **Custom field** — an extra data field added to issues beyond Jira's built-ins
  (e.g. a "Repository" dropdown).

The whole instance is administered from two web locations:
- **`admin.atlassian.com`** — organization-level: billing, products, users, security.
- **`coldboreballisticsllc.atlassian.net`** — the working site: projects, boards,
  spaces, and per-product settings.

---

## 2. Site and Plan

| Property | Value | Notes |
|---|---|---|
| Site URL | `coldboreballisticsllc.atlassian.net` | **Permanent** — cannot be renamed after creation. |
| Admin account | `admin@coldboreballisticsllc.com` | Site admin; Jira user; JSM agent; Confluence user. |
| Cloud ID | `f09947a5-08f9-4bb5-9f6c-4ae74d368f66` | Used by the REST API and MCP tools. |
| Jira Software plan | Free | 10 users. |
| Jira Service Management plan | Free | 3 agents; unlimited portal customers. |
| Confluence plan | Free | 10 users, 2 GB storage. |

The site name was chosen as the company-canonical `coldboreballisticsllc` so a buyer's
due-diligence team reads the company name directly off the URL. This is an
acquisition-readiness choice, not a cosmetic one.

---

## 3. Identity, Groups, and Permissions

### 3.1 Groups

Four groups exist. They are created and populated regardless of plan, but on the Free
plan **group membership does not yet drive project permissions** (see §11) — they are
staged so the permission model activates immediately on upgrade to Standard.

| Group | Intended access |
|---|---|
| `jira-admins` | Site and project administrators. |
| `jira-users` | Team members — create, edit, and transition issues across all projects. |
| `jira-reporters` | External or limited users — create issues and comment; no edit/delete. |
| `jsm-agents` | Service-desk agents — work ESUP tickets and manage queues. |

The admin account is a member of `jira-admins`, `jira-users`, and `jsm-agents`.

### 3.2 Site-level project roles

Two custom roles exist beyond Jira's built-in `Administrators`: **`Developer`** and
**`Reporter`**. These are the targets the permission scheme maps groups onto.

### 3.3 Permission scheme

A permission scheme named **"CBB Software Projects"** exists, mapping:
`Administrators → jira-admins`, `Developer → jira-users`, `Reporter → jira-reporters`.

> **Free-plan caveat:** the scheme is **created and populated but not assigned** to the
> projects — Jira Free blocks assigning a custom permission scheme. On upgrade to
> Standard, re-running the setup script assigns it automatically. Until then, the
> default Jira permissions apply.

---

## 4. Jira Project: DOPE (product)

| Property | Value |
|---|---|
| Name | ScopeDOPE |
| Key | `DOPE` |
| Type | Company-managed (classic), Jira Software |
| Board | Kanban |
| Purpose | All ScopeDOPE product work — bugs, features, improvements, engine, hardware. |
| Project avatar | ScopeDOPE pendulum icon |

### 4.1 Issue types

`Epic`, `Story`, `Task`, `Bug`, `Sub-task`, plus a custom **`Improvement`** type
(an enhancement to an existing feature).

### 4.2 Components

Ballistics Engine · Conditions & Sensors · Printing & Labels · Ammo Database ·
DOPE Entry & Sessions · Results & Output · File Format (.dope) · UI & Navigation ·
Onboarding · Settings.

### 4.3 Board columns

| Column | Status(es) mapped |
|---|---|
| Backlog | `Backlog` (Kanban backlog — off-board) |
| Ready to Work | `Ready to Work` |
| In Progress | `In Progress` |
| In Review | `In Review` |
| Done | `Done` |

Swimlanes: **Expedite** (top, WIP=1) + **by Epic** beneath. Blocked items are flagged in-place using Jira's built-in flag — no Blocked column.

### 4.4 Releases (fix versions)

`1.0.0` (in progress) and `2.0.0` (future).

### 4.4 Screens

Two screens carry the project's fields: **DOPE: Kanban Default Issue Screen** and
**DOPE: Kanban Bug Screen**. Both expose the External Visibility and Repository custom
fields (§8).

---

## 5. Jira Project: CBB (operations)

| Property | Value |
|---|---|
| Name | Cold Bore Ballistics — Operations |
| Key | `CBB` |
| Type | Company-managed (classic), Jira Software |
| Board | Kanban |
| Purpose | Company operations — legal, IP, brand, infrastructure, business development. |
| Project avatar | CBB wordmark logo |

### 5.1 Issue types

Primarily `Task` and `Epic` — admin/legal work does not fit the Bug/Story model.

### 5.2 Components

Legal & IP · Developer Accounts · App Store & Marketing · Brand Assets ·
Business Development · Infrastructure.

### 5.3 Releases

`1.0.0`.

### 5.4 Screens

**CBB: Kanban Default Issue Screen** and **CBB: Kanban Bug Screen** — both expose the
Repository custom field (§8).

---

## 6. Jira Service Management: ESUP (support)

| Property | Value |
|---|---|
| Name | ScopeDOPE Engineering Support |
| Key | `ESUP` |
| Type | Company-managed (classic), JSM |
| Purpose | Structured intake for bug reports and feature requests; triage gate before work is promoted to a DOPE or CBB issue. |
| Project avatar | ScopeDOPE icon |

### 6.1 Request types and work type — IMPORTANT

ESUP has **13 request types**. **Every one uses the JSM work type `Service Request`.**

> **Why this matters (a correction from the original plan):** the pre-implementation plan
> specified a Jira Software `Bug` issue type for bug request types. `Bug` is **not a valid
> JSM work type** — JSM only recognizes its own work types (Service Request, Incident,
> Problem, Change). Using `Bug` produced "Invalid work type / Invalid Workflow" errors on
> every bug request type. The fix: all 13 request types use `Service Request`. The
> bug-vs-feature distinction is carried by the **request-type name and portal group**, not
> by the underlying issue type. **If request types are ever recreated, use `Service
> Request` for all of them.**

The 13 request types, grouped:

**Report a Bug (7):** Bug — Crash or Freeze · Bug — Calculation / Accuracy ·
Bug — UI / Display · Bug — Printer / Label · Bug — Sensor / BLE Connectivity ·
Bug — Data / Session File · Bug — Performance

**Request a Feature (4):** Feature Request — New Feature · Feature Request — Improvement ·
Feature Request — Ammo Database · Feature Request — Hardware Support

**Other (2):** Hardware Validation Task · Admin / Legal / Business

### 6.2 Portal groups — manually configured

The three group headings above (Report a Bug / Request a Feature / Other) are **portal
groups**. The customer portal shows nothing until at least two portal groups exist with
request types assigned. **Portal-group creation is blocked by the Free-plan API** (POST
returns 405), so they are configured by hand in the UI — see the runbook.

### 6.3 Linking ESUP tickets to DOPE / CBB

A triaged ESUP ticket that needs work gets a **linked issue** in DOPE or CBB. The ESUP
ticket is the customer-facing record; the DOPE/CBB issue is the developer-facing work
item. They are kept distinct, not merged.

---

## 7. Resolutions

Jira resolutions are site-wide — all projects share the same list. The CBB resolution
set is defined here as a process convention; Jira Free does not support per-project
resolution schemes, so the "Applies To" guidance below is enforced by process, not
by the system.

| Resolution | Applies To | Meaning |
|---|---|---|
| **Fixed** | DOPE (bugs) | Bug confirmed and resolved in code. Use for Bug issue types only. |
| **Done** | DOPE (features/tasks), CBB | Work completed and delivered. Use for all non-bug issue types. |
| **Won't Do** | DOPE, CBB | Permanently out of scope — will never be done; category-level exclusion. |
| **Deferred** | DOPE, CBB | Intentionally postponed. Set `fixVersion` to the target version when deferring, if known. |
| **Duplicate** | DOPE, CBB | Duplicate of another issue. A `duplicates` issue link **must** be set before resolving. |
| **Cannot Reproduce** | DOPE (bugs) | Investigated; could not reproduce — no fix applied. |
| **Handled Differently** | CBB | Goal achieved via another means — automated, outsourced, or absorbed into another effort. |
| **Rejected** | CBB | Formally evaluated and declined — not a priority or fit; may be reconsidered. |
| **Cancelled** | CBB | Was planned or in progress, then stopped — business decision, vendor change, or dropped dependency. |
| **Obsolete** | CBB | Superseded by a later decision, architectural change, or external event. |
| **Other** | DOPE, CBB | Edge/corner case not covered above. **A comment explaining the close reason is required** before or at the time of resolution. |

### Key conventions

- **Fixed vs. Done:** Fixed is for Bug issue types only; Done is for everything else.
- **Won't Do vs. Rejected vs. Deferred:** Won't Do is permanent and categorical (this class will never be done). Rejected is issue-specific (evaluated and declined; may revisit). Deferred is time-based (wanted but not now).
- **Duplicate:** a `duplicates` link with no linked issue is a process violation.
- **Other:** a silent Other close (no comment) is a process violation.

### Jira default disposition

Jira ships five defaults. Their status once the new set is applied:

| Jira Default | Action | Result |
|---|---|---|
| Done | Keep | Already correct |
| Won't Fix | Rename | → `Won't Do` — **[MANUAL]** in admin UI |
| Duplicate | Keep | Already correct |
| Cannot Reproduce | Keep | Already correct |
| Incomplete | Delete | Dropped — incomplete work should not be a valid close state **[MANUAL]** in admin UI |

> **Free-plan constraint:** Jira Free blocks deleting or renaming default resolutions via
> the REST API. These two mutations are a required manual step in the Jira admin UI:
> **Settings → Issues → Resolutions**. The `setup_atlassian.py` script creates the nine
> new resolutions idempotently; it does not touch the defaults.

---

## 8. Custom Fields

### 7.1 External Visibility

| Property | Value |
|---|---|
| Type | Select list (single choice) |
| Options | `Hidden` (default) · `Public` · `Public — No Comments` |
| On screens | DOPE Default + Bug |
| Purpose | Machine-readable signal for a future external feedback board: which issues may surface publicly. |

> The default value (`Hidden`) must be set by hand — no REST endpoint exists for it.
> See the runbook.

### 7.2 Repository

| Property | Value |
|---|---|
| Field ID | `customfield_10209` |
| Type | Select list (**multiple** choice) |
| On screens | DOPE Default + Bug, CBB Default + Bug |
| Purpose | Records which GitHub repo(s) an issue touches. Multi-select so cross-repo work (e.g. an engine change spanning `scopedope-android` + `scopedope-shared`) is captured on one issue. |

**Options (11):** `scopedope-android` · `scopedope-shared` · `scopedope-ios` ·
`ble-bridge-android` · `ble-bridge-ios` · `ble-bridge-server` · `feedback-service` ·
`www.scope-dope.com` · `www.coldboreballisticsllc.com` · `cbb-utils` · `cbb-infra`.

> **`dope-format` is deliberately excluded.** Per the issue-tracking policy (§10), it is
> handled exclusively through GitHub Issues and is never tracked in Jira — so it must never
> appear as a Repository option.

This field gives a queryable issue-to-repo map (`JQL: Repository = "scopedope-android"`),
which is exactly the traceability a buyer's technical due diligence looks for.

---

## 9. Confluence Spaces

### 8.1 SCOPE — ScopeDOPE Engineering

| Property | Value |
|---|---|
| Space key | `SCOPE` (all caps) |
| Display alias | `SENG` may appear as a historical alias in some links. |
| Purpose | Product/engineering knowledge base; linked to the ESUP project so articles are suggested to reporters. |
| Home page | "ScopeDOPE Engineering" landing page (Jira links, status, KB index, platform/hardware). |

**Knowledge-base pages:** How to Report a Sensor or BLE Issue · Supported Hardware ·
Known Limitations and Workarounds · How to Export and Attach a .dope File · Current Release Status.

**ESUP knowledge base link:** The SCOPE space is linked to the ESUP project (ESUP project
settings → Knowledge base). KB articles are suggested automatically when reporters submit
tickets.

**Hardware target labels:** DOPE issues that are hardware-specific carry structured labels
for machine-queryable filtering. Convention: `hw:<driver_id>` matching the driver ID in
code. Labels applied as of 2026-06-05:

| Label | Issues |
|---|---|
| `hw:weatherflow_tactical` | DOPE-17, DOPE-18, DOPE-29, DOPE-30, DOPE-31 |
| `hw:niimbot_b21_pro` | DOPE-22, DOPE-33 |

JQL example: `project = DOPE AND labels = "hw:weatherflow_tactical"`

### 8.2 CBBOPS — Cold Bore Ballistics — Operations

| Property | Value |
|---|---|
| Space key | `CBBOPS` |
| Purpose | Internal operations: legal, IP, brand, infrastructure, business development. **Internal-only** content. |
| Home page | "Cold Bore Ballistics — Operations" landing page with a classification-notice panel. |

**Pages:** Brand Guidelines · Legal and IP Overview · Vendor and Partner Contacts ·
Infrastructure Overview.

> **Trade-secret boundary:** engine internals, the DOPE-Blend methodology, and the SPEC
> live in OneDrive (`04_-_Highly_Confidential/`), **never** in Confluence.

### 8.3 Space permissions

Intended: SCOPE → admins administer+edit, users edit, reporters read; CBBOPS → admins
administer+edit, users edit (reporters excluded). **Blocked on Confluence Free** — these
activate on upgrade to Standard. Until then default open access applies among
authenticated users.

---

## 10. GitHub for Jira Integration

The free **GitHub for Jira** app (published by Atlassian) is installed and connected to
the `ColdBoreBallistics` GitHub organization.

Once connected, any commit, branch, or pull request whose name contains a Jira key
(e.g. `DOPE-42`, `CBB-7`) is automatically linked to that issue and surfaces in the
issue's **Development** panel — commits, branches, PR status, and CI build status — with
no extra steps.

The issue's Development panel also offers a manual **Create branch** link: one click opens
a dialog to create a correctly named branch in a chosen repo. This is the recommended way
to start work on a post-1.0.0 issue (the Repository field records which repo after the
fact; it does not auto-create branches).

---

## 11. Issue Tracking Policy

This policy is authoritative in `CLAUDE.md`; restated here for the operating team.

| Repo visibility | Issue tracker |
|---|---|
| **Public — `dope-format` only** | **GitHub Issues.** Community-facing; never migrated to Jira. |
| **All private repos** | **Jira** (projects DOPE / CBB / ESUP). |

- **Never create Jira issues for `dope-format`** — directive, no exceptions.
- **Never use GitHub Issues on private repos** for work tracking.

**Post-1.0.0 branch naming:** `dev-<version>-<JIRA-KEY>_<slug>` for private repos
(e.g. `dev-1.0.1-DOPE-42_ble_timeout`); `dev-<version>-<gh-number>_<slug>` for
`dope-format`.

---

## 12. Free-Plan Limitations (as-built constraints)

Six capabilities are blocked by the Atlassian Free plan at the **API** level. Each is
either configured by hand in the UI or deferred until a Standard upgrade. **Do not retry
these in code** — they will fail.

| Capability | Blocked call | Current handling |
|---|---|---|
| Delete/rename default resolutions | No REST endpoint on Free | Configured by hand in the UI (see §7). |
| Assign custom permission scheme | `PUT /project/{key}/permissionscheme` → 403 | Deferred to Standard; scheme is staged. |
| Assign project role actors | `POST /project/{key}/role/{id}` → 400 | Deferred to Standard. |
| Create JSM portal groups | `POST /servicedeskapi/requesttypegroup` → 405 | Configured by hand in the UI. |
| Set Confluence space permissions | `POST /wiki/.../space/{key}/permission` → 403 | Deferred to Standard. |
| (Plan caps) | — | 10 Jira users · 3 JSM agents · 10 Confluence users · 2 GB storage · automation run limits. |

**On upgrade to Standard:** re-running `setup_atlassian.py` (see the rebuild guide)
applies the permission scheme, role actors, and space permissions automatically. The
portal groups remain a manual UI task.

---

## 13. Credentials

### API Keys

Secrets are populated manually via `az keyvault secret set` after key creation. Atlassian API keys are tied to the user account that created them.

| Friendly name | Account | Secret location | Expires | Purpose |
|---|---|---|---|---|
| `atlassian-admin-api-key` | `admin@coldboreballisticsllc.com` | `kv-cbb-shared-prod` → `atlassian-admin-api-key` | 2027-06-10 | Atlassian admin API token — scripts and Claude Code MCP access to Jira and Confluence |
| `atlassian-admin-email` | — | `kv-cbb-shared-prod` → `atlassian-admin-email` | Never | Atlassian admin account email — companion to `atlassian-admin-api-key` for script auth |

> API keys are created at **id.atlassian.com → Security → API tokens**. To rotate: create a new token, store it in Key Vault, then revoke the old one.

---

## 14. Reference IDs

Stable identifiers for API and MCP use.

| Resource | ID |
|---|---|
| Cloud ID | `f09947a5-08f9-4bb5-9f6c-4ae74d368f66` |
| Repository custom field | `customfield_10209` |
| Repository field context | `10315` |
| SCOPE Confluence space ID | `458754` |
| CBBOPS Confluence space ID | `720898` |
| DOPE board ID | `70` — https://coldboreballisticsllc.atlassian.net/jira/software/c/projects/DOPE/boards/70 |
| CBB board ID | `103` — https://coldboreballisticsllc.atlassian.net/jira/software/c/projects/CBB/boards/103 |
| DOPE: Kanban Default Issue Screen | `10045` (tab `10048`) |
| DOPE: Kanban Bug Screen | `10046` (tab `10049`) |
| CBB: Kanban Default Issue Screen | `10047` (tab `10050`) |
| CBB: Kanban Bug Screen | `10048` (tab `10051`) |

> Project numeric IDs and avatar IDs shift if projects are recreated; the keys
> (`DOPE`, `CBB`, `ESUP`) and the Cloud ID are the stable handles to rely on.

---

## Document Control

| Field | Value |
|---|---|
| **Document owner** | `jschwefel@coldboreballisticsllc.com` |
| **Classification** | Confidential (03_-_Confidential/) |
| **Location** | `OneDrive/CBB_Corporate/03_-_Confidential/Infrastructure/Atlassian/Atlassian_Architecture_Reference.md` |
| **Cross-references** | `Atlassian_Operating_Runbook.md`; `Atlassian_Rebuild_Guide.md`; `Atlassian_Acquisition_Brief.md` |
| **Created** | 2026-06-06 |
| **Last updated** | 2026-06-06 |
| **Next full review due** | 2027-06-06 |

---

## Revision Control Block

| Rev | Date | Changed By | Reviewed By | Approved By | Summary |
|-----|------|------------|-------------|-------------|---------|
| 0.9 | 2026-06-06 | jschwefel | — | — | Initial release |
| DRAFT | 2026-06-08 | jschwefel | — | — | New Kanban boards created: DOPE ID 70, CBB ID 103; board column layout documented (§4.3); DOPE/CBB workflow statuses documented |
| DRAFT | 2026-06-10 | jschwefel | — | — | §7 Resolutions added (11-resolution set, Jira default disposition, process conventions); §§8–14 renumbered; §12 Free-Plan Limitations updated with resolution-cleanup row |
