A portable role definition repository for infrastructure and platform engineering teams. Covers 34 domains grouped into 7 chapters, and 226 roles — spanning the full hierarchy from Engineer to Senior Engineer, Architect, Lead Architect, Principal Architect, Chapter Lead, Technical Area Lead (TAL), Product Area Lead (PAL), and C-Suite.
Repository: github.com/JeanKadang/DOC-ITRoles (public). Issues and committed work are tracked on the Issues tab.
Most role catalogues live as static documents — a Confluence page or a slide deck, written once and never re-checked. This one is held to the same discipline as the software that serves it: every certification recommendation is checked against an issuer-controlled source before it's marked verified (docs/CREDENTIAL_REGISTRY.md), every durable structural decision is recorded with its reasoning rather than just its outcome (docs/adr/), and the catalogue's own structure is validated and tested (374 automated tests, npm run validate) rather than trusted on sight. The result is content you can audit, not just read — you can tell what's been verified, by whom, and as of when, instead of taking a role definition on faith.
Node.js v18 or later. The server, core tooling, and Node test suite use only
Node.js built-in modules — no npm install needed. Browser tests have a separate
Node.js requirement described under Browser journey and accessibility tests.
winget install OpenJS.NodeJS.LTSClose and reopen your terminal after installation, then verify:
node --versionDon't have winget? Install it from the App Installer page in the Microsoft Store, or download Node.js directly from nodejs.org.
Start:
start.batstart.bat picks the first free port starting at 3000 (trying up to 3010), starts the server on it, and automatically opens your default browser to it — no manual URL needed. If port 3000 is already in use by something else (another dev server, etc.), it moves on to the next free port instead of touching that process.
Or directly:
node server.jsThen open http://localhost:3000 in your browser (does not auto-open — only start.bat does that).
To use a different port:
$env:PORT = 8080; node server.js| Feature | How to use |
|---|---|
| Browse roles | Expand a domain in the left sidebar |
| Search | Type in the search box — filters roles, domains, and chapters instantly. Queries of 3+ characters additionally search role content and prepend a 🔎 Content matches group with snippets |
| Role Matrix | Click 📊 Matrix in the header — shows all roles in a domain × level grid |
| Org chart | Click 🌳 Org in the header — interactive hierarchy of chapters, domains, and roles plus the leadership line |
| Relationship graph | Click 🔗 Graph in the header — force-directed view of how domains collaborate |
| Career paths | Click 📈 Careers in the header — flow view of progression and cross-domain mobility |
| Career stepper | Open a role — its Career Development Path renders as a clickable stepper linking previous and next roles |
| Distribution charts | Shown on the welcome screen — roles per chapter and per level, each with an accessible table fallback |
| Compare two roles | Open a role, then click ⚖️ Compare and select a second role |
| Print a role | Open a role, click 🖨️ Print — sidebar and controls are hidden in print |
| Export a role | Open a role, click ⬇️ Export — downloads it as a .md file |
| Export the matrix | In Matrix view, click ⬇️ Export CSV |
| Track stale roles | Click ⏰ Stale (N) in the header (shown only when roles are overdue) — lists roles with no review date or one older than 12 months, with CSV export |
| Dark mode | Click the 🌙 Dark toggle in the header |
| Browse by chapter | Click a chapter in the sidebar to open its narrative panel (purpose, cross-chapter collaborations, live domain/role counts, Chapter Lead link) |
The 34 domains are grouped into 7 chapters, each led by a Chapter Lead:
| # | Chapter | Focus |
|---|---|---|
| 1 | ☁️ Cloud, Platform & Infrastructure | Cloud, containers, virtualisation, hardware, OS, network, FinOps |
| 2 | 🔄 DevOps & Delivery | CI/CD, developer experience, application platforms, integration |
| 3 | 📊 Data & AI | Data platform, storage, databases, AI governance |
| 4 | 🔒 Security & Identity | Security architecture, IAM/PAM, data protection, directory services |
| 5 | 🖥️ End User & Workplace | Client platform, endpoint management, Microsoft 365, service desk |
| 6 | 🎯 Service & Governance | ITSM, configuration management, service management, enterprise architecture |
| 7 | 👑 Leadership | C-Suite, SVP, CISO, Chapter Leads, TAL, PAL, cross-cutting leadership |
See docs/CHAPTERS_OVERVIEW.md for the full breakdown and docs/chapters/*.md for each chapter's detail. Domain and role counts are computed live from Roles/ — never hand-maintained — to prevent drift.
| Level | Badge | Description |
|---|---|---|
| C-Suite (CEO, CTO, CIO, CFO, CISO) | Distinct per role | Executive leadership — organisation-wide accountability |
| SVP | Slate | Senior VP of Technology — cross-chapter executive oversight |
| Product Area Lead (PAL) | Dark navy | Cross-domain delivery, people, and budget leadership |
| Technical Area Lead (TAL) | Blue | Cross-domain technical direction and governance |
| Chapter Lead | Teal | Leads one of the 7 chapters; owns its domains and Chapter Leads report to TAL/PAL |
| Principal Architect | Gold | Senior IC — org-wide architecture strategy |
| Lead Architect | Amber | Multi-domain architecture leadership and standards |
| Architect | Purple | Domain-level technical authority and design |
| Senior Engineer | Blue | Autonomous delivery and mentoring within a domain |
| Engineer | Green | Execution and learning within a domain |
| Product Owner | Orange | Backlog and roadmap ownership for a domain |
roles_master/
├── .github/
│ ├── workflows/ci.yml # CI: tests, validation + count + vendor checks, markdownlint, browser
│ ├── workflows/pr-label.yml # Labels PRs from their conventional-commit title prefix
│ └── dependabot.yml # Weekly GitHub Actions + npm update checks
├── Roles/ # All role definitions (34 domains, 226 roles)
│ ├── leadership/ # SVP, CISO, Chapter Leads, TAL, PAL
│ ├── c_suite/ # CEO, CTO, CIO, CFO
│ ├── cloud_platforms/ # Azure, AWS, GCP + Lead/Principal
│ ├── devops/ # DevOps, Developer Experience, Platform Reliability
│ ├── ai_governance/ # AI Governance, AI Platform (classical MLOps)
│ ├── modern_infrastructure/ # GenAI Platform, Infrastructure Automation
│ ├── data_engineering/ # Data Platform, Data Mesh, DataOps
│ ├── service_management/ # TPM, Major Incident, Change/Release, Vendor/Asset
│ ├── security/ # README.md explains scope
│ ├── security_cross_platform/ # README.md explains scope
│ ├── security_identity/ # README.md explains scope
│ └── ... # 34 domains total
├── docs/ # Governance and reference documentation
│ ├── role_template.md # Template for new roles
│ ├── CREDENTIAL_REGISTRY.md # Audited credential evidence and audit boundary
│ ├── CROSS_DOMAIN_INTERACTIONS.md # Domain ownership and escalation paths
│ ├── SCENARIOS.md # A cross-domain escalation walked through end to end
│ ├── SKILLS_PROGRESSION.md # Career progression framework
│ ├── ONBOARDING_TEMPLATE.md # 30/60/90 day onboarding plan template
│ ├── onboarding_*_supplement.md # Level overlays: Engineer, Senior, Architect, PO
│ ├── onboarding_chapter_lead_template.md # Chapter Lead-specific onboarding variant
│ ├── CHAPTERS_OVERVIEW.md # The 7 chapters: focus, lead, detail link
│ ├── adr/ # Architecture Decision Records (durable decisions + reasoning)
│ ├── chapters/ # Per-chapter narrative (rendered in the viewer)
│ └── ... # see the Governance documents table below for the full list
├── data/
│ └── credentials.json # Credential registry: audited records + audited_roles list
├── scripts/ # Validators, generators, and migration/audit tooling
│ ├── check-counts.js # Verifies README counts vs filesystem — `npm run check-counts`
│ ├── verify-vendor.js # Checksums vendor/* against manifest.json — `npm run verify-vendor`
│ └── ... # see package.json for the full script list
├── test/ # node:test suite (374 tests: server, validator, viewer logic, generators, docs)
├── vendor/ # Vendored third-party assets (marked, DOMPurify, Chart.js, ECharts)
├── LICENSES/ # Full text of the licenses named in LICENSE
├── server.js # Node.js web server (no dependencies)
├── catalogueConfig.js # Single source for domains, chapters, labels, and icons
├── credentialRegistry.js # Credential registry read/validation logic
├── roleMeta.js # Shared role metadata parser (server + validator)
├── viewer-logic.js # Browser-side pure logic, shared with the test suite
├── validate-roles.js # Content validator — `npm run validate`
├── index.html # Web UI markup, styles, and view wiring
├── start.bat # Windows launcher (auto-picks a free port, opens browser)
├── package.json # See its "scripts" section for the full command list
├── .gitattributes # Pins LF line endings; excludes vendor/ from normalization
├── CONTRIBUTING.md # Evidence standards and contribution workflow
├── LICENSE # Licensing split: MIT (software) / CC BY 4.0 (catalogue content)
├── SECURITY.md # Security policy and vulnerability reporting
├── CHANGELOG.md # Version history (Keep a Changelog)
└── README.md # This file
- Copy
docs/role_template.mdinto the appropriate folder underRoles/. - Name the file using the pattern:
<technology>_<level>.md- Standard levels:
architect,senior_engineer,engineer,product_owner - Special levels:
product_area_lead,technical_area_lead,cloud_lead_architect,cloud_principal_architect - Example:
Roles/kubernetes/kubernetes_senior_engineer.md
- Standard levels:
- Fill in all 14 sections following the template.
- Run
npm run validateto confirm the file has all required sections and metadata. - Restart the server — new roles are picked up automatically on each request.
- Add one record to
DOMAIN_LISTincatalogueConfig.js— a lowercaseid, its label, icon, chapter, order, and any legacy aliases. This is the single source bothserver.jsand the viewer read from; nothing else needs editing. - Create the exact
Roles/<domain-id>/directory and its role files. - Run
npm run validateandnpm run check-counts.
Each role file follows the canonical 14-section structure. See docs/role_template.md for full guidance.
# Role Title
| Field | Value |
|---|---|
| **Role ID** | `stable-kebab-case-id`, frozen once assigned (ADR-0005) |
| **Domain** | Domain Name |
| **Chapter:** | The chapter this domain belongs to |
| **Role Level** | Architect / Senior Engineer / Engineer / Product Owner |
| **Reports To** | Role this position reports to |
| **Direct Reports** | Roles managed, or "None" for individual contributors |
| **Content Owner** | Durable role/team identifier accountable for the content (ADR-0004) |
| **Review Status** | `reviewed` / `mechanical` / `unreviewed` (ADR-0004) |
| **Last Reviewed** | YYYY-MM |
---
## Role Overview
## Role Scope & Boundaries
## Business Impact
## Key Responsibilities
## Key Decisions & Accountabilities
## Required Skills & Qualifications
## Interactions with Other Roles
## Key Technologies
## Typical Day-to-Day Activities
## Key Performance Indicators
## Remote Work Considerations
## Career Development Path
## Recommended Certifications & Learning Paths| Document | Purpose |
|---|---|
CONTRIBUTING.md |
Evidence standards, substantive review expectations, and contribution workflow |
docs/CREDENTIAL_REGISTRY.md |
Audited credential evidence, ownership, lifecycle, contributor policy, and migration policy |
docs/adr/README.md |
Durable catalogue and architecture decisions, ADR lifecycle, and index |
docs/CROSS_DOMAIN_INTERACTIONS.md |
Domain ownership boundaries, key relationships, escalation paths |
docs/SCENARIOS.md |
A cross-domain escalation walked through end to end, linking the real role pages at each step |
docs/ADOPTING.md |
How to fork and trim this catalogue for your own organisation's size |
docs/SKILLS_PROGRESSION.md |
Engineer → Senior → Architect career ladder per domain |
docs/ONBOARDING_TEMPLATE.md |
30/60/90 day plan template for new hires |
docs/onboarding_*_supplement.md |
Level overlays (Engineer, Senior Engineer, Architect, Product Owner) — used alongside the base template, adding only what differs by level |
docs/onboarding_chapter_lead_template.md |
Onboarding variant for incoming Chapter Leads |
docs/CHAPTERS_OVERVIEW.md |
The 7 chapters, their focus, and links to per-chapter detail |
docs/improvements_and_recommendations.md |
Closed. Narrative of the four 2026 review cycles. Open work is in GitHub Issues; what shipped is in CHANGELOG.md |
CHANGELOG.md |
Version history of the codebase (Keep a Changelog format) |
SECURITY.md |
Security policy and how to report a vulnerability |
vendor/README.md |
Vendored dependency provenance, licence notices, verification, and upgrade process |
npm testRuns the Node.js built-in test runner (node --test) against every test/*.test.js file — 374 tests covering the server (path-traversal protection on /api/role, /api/doc, and /vendor/*, API response shapes), role-metadata parsing (including the BOM-prefixed-file edge case), the content validator, the credential registry, viewer logic, doc-link integrity, and every generator/migration script.
Node.js v20 or later is required for browser tests. The pinned Playwright
development tooling does not support Node.js 18; the server, core tooling, and
npm test remain supported on Node.js 18 without installing packages.
npm ci
npx playwright install chromium firefox webkit
npm run test:browserPlaywright starts the local Node server automatically and runs the critical home,
search, compare, responsive-navigation, keyboard, and accessibility journeys in
Chromium, Firefox, and WebKit. Failure output is written to test-results/; the
HTML report is written to playwright-report/ in CI.
npm run validateChecks every role file against the canonical 14-section template and required metadata fields (Domain, Role ID, Role Level, Reports To, Direct Reports, Content Owner, Review Status, Last Reviewed), and requires the Interactions table to carry an Interaction Mode column. It also validates credential-registry structure, rejects unknown or duplicate credential references, requires complete marker coverage for audited_roles, and warns when credential verification is stale. Missing sections, metadata, unknown references, or the mode column are reported as errors (exit code 1); non-canonical values (e.g. an unrecognized Role Level, or a Domain that doesn't match its folder's canonical label) and stale credential verification are reported as warnings. Pass --strict to fail the build on warnings too.
Duplicate H1 role titles across the catalog are also errors — the same title appearing in two files is a content-integrity bug that shipped twice before this check existed.
npm run check-countsCompares README.md's count-bearing sentences ("N domains grouped into N chapters, and N roles") against the actual Roles/ filesystem and fails (exit code 1) on any mismatch — a guard-rail against count drift, since these numbers used to be hand-maintained and go stale silently.
npm run verify-vendorChecksums every file under vendor/ against vendor/manifest.json's recorded SHA-256, so a tampered or accidentally-modified third-party asset (including marked and DOMPurify, which feed the viewer's HTML sanitization) fails the build rather than merging unnoticed.
.github/workflows/ci.yml runs four jobs on every push/PR to main, all required:
- Tests (
npm test) — on a Node 18/22 matrix. - Role content validation — three steps in sequence:
npm run validate(every role file matches the canonical template),npm run check-counts(README's counts match the filesystem), andnpm run verify-vendor(vendored assets match their recorded checksums). - Markdown lint (
markdownlint-cli2, config in.markdownlint.json). - Browser journeys (
npm run test:browser) — Chromium, Firefox, and WebKit share a 30-minute job budget (headroom for a slow runner mirror provisioning browser engines, not typical runtime — a normal run takes roughly 2.5 minutes), with failure diagnostics retained for seven days. A PR that touches nothing browser-relevant can carry the maintainer-appliedbrowser-not-requiredlabel to waive this job without weakening it as a required check for everything else.
- No external CDN dependencies — all third-party browser libraries (
marked,DOMPurify, chart libraries) are vendored locally undervendor/and served byserver.js. - All rendered markdown is sanitized with DOMPurify before insertion into the DOM, and dynamic strings (role titles, levels, labels, search input) are HTML-escaped — a malicious or copy-pasted
.mdfile cannot execute script in the viewer. - Every response sets
X-Content-Type-Options,X-Frame-Options,Referrer-Policy, and aContent-Security-Policyrestricting script/style/connect origins to same-origin. /api/role,/api/doc, and/vendor/*all validate requested paths against traversal (..) and enforce their respective root directories.
DOC-ITRoles uses separate licences for software and catalogue content:
- Source code, scripts, tests, workflows, configuration, and code samples are available under the MIT License.
- Role definitions, catalogue data, and documentation are available under the Creative Commons Attribution 4.0 International License.
- Vendored third-party files retain their upstream licences and notices, as
documented in
vendor/README.md.
For CC BY 4.0 attribution, credit "Jean Kadang and DOC-ITRoles contributors", link to this repository and the licence, and indicate whether changes were made. For example:
IT Roles Library by Jean Kadang and DOC-ITRoles contributors, licensed under CC BY 4.0. Source: DOC-ITRoles. Changes were made.
See LICENSE for the authoritative scope and third-party exceptions.
- Near-single-file UI. Markup, styles, and view wiring live together in
index.html(~3,000 lines) with no build step or bundler, so the app stays portable. The one deliberate exception isviewer-logic.js, which holds the pure functions (level ordering, stale-role computation, career-path parsing) so thenode:testsuite can import and test them directly — logic that was previously untestable and shipped two silent bugs. Keep new pure logic there and new DOM work inindex.html. - Zero runtime dependencies.
server.jsuses only Node.js built-ins; the third-party browser libraries (marked,DOMPurify, Chart.js, ECharts) are vendored undervendor/rather than pulled from a CDN, so the app works fully offline.