SDK-Docs Structure
Purpose
sdk-docs is the knowledge base for content that spans services, serves non-developer audiences, or has a lifecycle independent of code releases.
| Belongs in sdk-docs | Belongs in sdk-core repos |
|---|---|
| Cross-service runbooks & operations | Service-specific README, AGENTS.md |
| Platform-wide architecture (ADRs) | Component-specific design docs |
| Business content (proposals, evaluations) | API docs, code examples |
| Customer use-cases & project docs | CHANGELOG, migration guides |
| Historical/legacy knowledge | Config documentation |
| Onboarding & training materials | Build/test instructions |
| Security assessments, pentests | — |
Structure
./
│
├── operations/ # Cross-service ops (SRE audience)
│ ├── runbooks/
│ │ ├── platform/ # Platform-wide procedures
│ │ ├── kubernetes/ # K8s operations
│ │ ├── azure/ # Cloud-specific
│ │ ├── generic/ # General operational patterns
│ │ └── services/ # Service-specific runbooks
│ ├── alerts/ # Alert definitions & response
│ ├── cheatsheets/ # Quick reference guides
│ └── monitoring/ # Dashboards, observability
│
├── architecture/ # Platform-wide decisions (Dev/Arch audience)
│ ├── adrs/ # Architecture Decision Records
│ ├── system-design/ # Cross-service flows, diagrams
│ ├── security/ # ITSEC, pentests, threat models
│ └── evaluations/ # Technical evaluations
│
├── business/ # Non-technical (Sales/PM audience)
│ ├── proposals/ # Customer offers (Angebote)
│ ├── evaluations/ # Business/tech evaluations
│ └── presentations/ # Slide decks, demos
│
├── projects/ # Customer implementations
│ ├── charginghub/ # Audi ChargingHub
│ ├── energy/ # Energy sector projects
│ ├── weischer - pbs/ # Weischer Prebid Server
│ └── __completed/ # Delivered projects (reference)
│
├── onboarding/ # New team members (All audiences)
│ ├── platform-overview/ # What is SDK?
│ ├── getting-started/ # Setup guides
│ └── team/ # Processes, contacts
│
├── archive/ # Historical knowledge
│ ├── legacy/ # Superseded docs, old projects
│ │ ├── arc42/ # Original architecture docs (2020-21)
│ │ ├── itsec/ # Security documentation (2023)
│ │ ├── readthedocs/ # User documentation stubs
│ │ ├── superb-data-kraken-docs/ # Open-source user docs
│ │ ├── documentations/ # Infrastructure/ops docs
│ │ ├── helper_collection/ # Migration scripts (historical)
│ │ └── projectA/ # DuckDB/Superset decisions
│ └── legacy-comparisons/ # Analysis of legacy vs current docs
│
├── assets/ # Images, attachments
│
├── templates/ # Doc templates
│ ├── runbook.md
│ ├── adr.md
│ └── project.md
│
├── AGENTS.md # Agent instructions
├── DOCUMENT_CLASSIFICATION_GUIDE.md
├── README.md
└── STRUCTURE.md # This file
Folder Descriptions
operations/
Cross-service operational documentation for SRE and on-call engineers.
- runbooks/: Step-by-step procedures for incidents and maintenance
platform/: Platform-wide procedures (cluster upgrades, backups)kubernetes/: K8s-specific operationsazure/: Cloud provider proceduresincident-response/: On-call playbooks
- alerts/: Alert definitions, thresholds, and response guides
- monitoring/: Dashboard documentation, observability setup
architecture/
Platform-wide architectural decisions and security documentation.
- adrs/: Architecture Decision Records following ADR format
- system-design/: Cross-service data flows, sequence diagrams, integration patterns
- security/: ITSEC gap analyses, penetration test results, threat models
business/
Non-technical documentation for sales, project management, and business development.
- proposals/: Customer offers and project proposals (formerly
angebote/) - evaluations/: Technology evaluations and comparisons (formerly
evaluierungen/) - presentations/: Slide decks, demo materials, marketing content
projects/
Customer-specific implementation documentation.
- active/: Current customer engagements with project-specific docs
- completed/: Delivered projects for reference and lessons learned
onboarding/
Curated learning path for new team members.
- platform-overview/: High-level introduction to SDK platform
- getting-started/: Environment setup, access provisioning
- team/: Team structure, processes, communication channels
archive/
Historical documentation preserved for reference.
- legacy/: Superseded docs, deprecated projects, historical context
arc42/: Original architecture documentation (2020-21) - foundational concepts still validitsec/: Security documentation (2023) - seearchitecture/security/ITSEC Gap Analysis.mdfor migration guidancereadthedocs/: User documentation structure (~75% incomplete stubs)superb-data-kraken-docs/: Open-source user docs with working code examplesdocumentations/: Infrastructure and operational documentationhelper_collection/: Database migration scripts and utilities (completed 2024)projectA/: DuckDB and Superset architecture decisions (implemented)
- legacy-comparisons/: Detailed analysis comparing legacy documentation against current docs and codebase
- Each comparison documents what’s still relevant, what’s stale, what’s missing, and disposition recommendations
- See
legacy-comparisons/README.mdfor the index and cross-cutting findings
templates/
Reusable document templates for consistency.
Migration Mapping
| Current Location | New Location | Notes |
|---|---|---|
runbooks/ | operations/runbooks/ | Restructure by scope |
SDK/arch/ | architecture/system-design/ | — |
SDK/pentest/ | architecture/security/ | — |
SDK/alerts/ | operations/alerts/ | — |
angebote/ | business/proposals/ | Rename to English |
evaluierungen/ | business/evaluations/ | Rename to English |
usecases/ | projects/active/ or completed/ | Split by status |
legacy/ | archive/legacy/ | — |
deployment/ | operations/runbooks/platform/ | Merge into runbooks |
SDK/Overview.md | onboarding/platform-overview/ | — |
What’s Explicitly NOT in sdk-docs
These belong in the respective sdk-core repositories:
- Service-specific READMEs and AGENTS.md
- API documentation (generated or code-adjacent)
- CHANGELOGs and release notes
- Build, test, and deployment instructions per service
- Component-specific design documents
Legacy Documentation
The archive/legacy/ folder contains historical documentation from various sources. Each legacy folder has been analyzed and compared against current documentation in archive/legacy-comparisons/.
Key Legacy Sources
| Folder | Content | Value |
|---|---|---|
arc42/ | Original 2020-21 architecture | Core principles (org/space model, RBAC, microservices) still valid |
itsec/ | 2023 security assessment | Concepts valid; see ITSEC Gap Analysis for extraction guidance |
superb-data-kraken-docs/ | Open-source user docs | Best user-facing content; working sdk-client examples |
documentations/ | Ops/infrastructure | Mix of valid concepts and deprecated tooling |
projectA/ | DuckDB/Superset decisions | Architecture decisions implemented in superset-tenant-operator |
readthedocs/ | User doc structure | ~75% incomplete; useful as template |
helper_collection/ | Migration scripts | Historical; superseded by Flyway |
Using Legacy Comparisons
Before migrating or referencing legacy content, consult archive/legacy-comparisons/:
- Check the relevant comparison document for uncertainty assessments
- Note what content is verified vs. needs runtime verification
- Follow disposition recommendations (migrate, archive, delete)
Related Documentation
- sdk-core/DOCUMENTATION_TRUST.md: Component documentation trustworthiness ratings
- sdk-core/PROJECT_USAGE.md: Project usage matrix and status
- sdk-core/system.md: Current system component status
- architecture/security/ITSEC Gap Analysis.md: Authoritative guidance on itsec migration