mirror of
https://github.com/K-Dense-AI/claude-scientific-skills.git
synced 2026-03-28 07:33:45 +08:00
docs(references): port style guides, 24 diagram guides, and 9 templates from opencode
All content ported from borealBytes/opencode under Apache-2.0 license with
attribution headers prepended to each file.
- references/markdown_style_guide.md (~733 lines): full markdown formatting,
citation, collapsible sections, emoji, Mermaid integration, and template
selection guide
- references/mermaid_style_guide.md (~458 lines): full Mermaid standards —
emoji set, classDef color palette, accessibility (accTitle/accDescr),
theme neutrality (no %%{init}), and diagram type selection table
- references/diagrams/ (24 files): per-type exemplars, tips, and templates
for all Mermaid diagram types
- templates/ (9 files): PR, issue, kanban, ADR, presentation, how-to,
status report, research paper, project docs
Source: https://github.com/borealBytes/opencode
This commit is contained in:
borealBytes
@@ -0,0 +1,246 @@
|
||||
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
|
||||
|
||||
# Class Diagram
|
||||
|
||||
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
|
||||
|
||||
**Syntax keyword:** `classDiagram`
|
||||
**Best for:** Object-oriented design, type hierarchies, interface contracts, domain models
|
||||
**When NOT to use:** Database schemas (use [ER](er.md)), runtime behavior (use [Sequence](sequence.md))
|
||||
|
||||
---
|
||||
|
||||
## Exemplar Diagram
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
accTitle: Payment Processing Class Hierarchy
|
||||
accDescr: Interface and abstract base class with two concrete implementations for credit card and digital wallet payment processing
|
||||
|
||||
class PaymentProcessor {
|
||||
<<interface>>
|
||||
+processPayment(amount) bool
|
||||
+refund(transactionId) bool
|
||||
+getStatus(transactionId) string
|
||||
}
|
||||
|
||||
class BaseProcessor {
|
||||
<<abstract>>
|
||||
#apiKey: string
|
||||
#timeout: int
|
||||
+validateAmount(amount) bool
|
||||
#logTransaction(tx) void
|
||||
}
|
||||
|
||||
class CreditCardProcessor {
|
||||
-gateway: string
|
||||
+processPayment(amount) bool
|
||||
+refund(transactionId) bool
|
||||
-tokenizeCard(card) string
|
||||
}
|
||||
|
||||
class DigitalWalletProcessor {
|
||||
-provider: string
|
||||
+processPayment(amount) bool
|
||||
+refund(transactionId) bool
|
||||
-initiateHandshake() void
|
||||
}
|
||||
|
||||
PaymentProcessor <|.. BaseProcessor : implements
|
||||
BaseProcessor <|-- CreditCardProcessor : extends
|
||||
BaseProcessor <|-- DigitalWalletProcessor : extends
|
||||
|
||||
style PaymentProcessor fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
|
||||
style BaseProcessor fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
|
||||
style CreditCardProcessor fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
|
||||
style DigitalWalletProcessor fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
- Use `<<interface>>` and `<<abstract>>` stereotypes for clarity
|
||||
- Show visibility: `+` public, `-` private, `#` protected
|
||||
- Keep to **4–6 classes** per diagram — split larger hierarchies
|
||||
- Use `style ClassName fill:...,stroke:...,color:...` for light semantic coloring:
|
||||
- 🟣 Purple for interfaces/abstractions
|
||||
- 🔵 Blue for base/abstract classes
|
||||
- 🟢 Green for concrete implementations
|
||||
- Relationship arrows:
|
||||
- `<|--` inheritance (extends)
|
||||
- `<|..` implementation (implements)
|
||||
- `*--` composition · `o--` aggregation · `-->` dependency
|
||||
|
||||
---
|
||||
|
||||
## Template
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
accTitle: Your Title Here
|
||||
accDescr: Describe the class hierarchy and the key relationships between types
|
||||
|
||||
class InterfaceName {
|
||||
<<interface>>
|
||||
+methodOne() ReturnType
|
||||
+methodTwo(param) ReturnType
|
||||
}
|
||||
|
||||
class ConcreteClass {
|
||||
-privateField: Type
|
||||
+methodOne() ReturnType
|
||||
+methodTwo(param) ReturnType
|
||||
}
|
||||
|
||||
InterfaceName <|.. ConcreteClass : implements
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complex Example
|
||||
|
||||
An event-driven notification platform with 11 classes organized into 3 `namespace` groups — core orchestration, delivery channels, and data models. Shows interface implementation, composition, and dependency relationships across layers.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
accTitle: Event-Driven Notification Platform
|
||||
accDescr: Multi-namespace class hierarchy for a notification system showing core orchestration, four delivery channel implementations, and supporting data models with composition and dependency relationships
|
||||
|
||||
namespace Core {
|
||||
class NotificationService {
|
||||
-queue: NotificationQueue
|
||||
-registry: ChannelRegistry
|
||||
+dispatch(notification) bool
|
||||
+scheduleDelivery(notification, time) void
|
||||
+getDeliveryStatus(id) DeliveryStatus
|
||||
}
|
||||
|
||||
class NotificationQueue {
|
||||
-pending: List~Notification~
|
||||
-maxRetries: int
|
||||
+enqueue(notification) void
|
||||
+dequeue() Notification
|
||||
+retry(attempt) bool
|
||||
}
|
||||
|
||||
class ChannelRegistry {
|
||||
-channels: Map~string, Channel~
|
||||
+register(name, channel) void
|
||||
+resolve(type) Channel
|
||||
+healthCheck() Map~string, bool~
|
||||
}
|
||||
}
|
||||
|
||||
namespace Channels {
|
||||
class Channel {
|
||||
<<interface>>
|
||||
+send(notification, recipient) DeliveryAttempt
|
||||
+getStatus(attemptId) DeliveryStatus
|
||||
+validateRecipient(recipient) bool
|
||||
}
|
||||
|
||||
class EmailChannel {
|
||||
-smtpHost: string
|
||||
-templateEngine: TemplateEngine
|
||||
+send(notification, recipient) DeliveryAttempt
|
||||
+getStatus(attemptId) DeliveryStatus
|
||||
+validateRecipient(recipient) bool
|
||||
}
|
||||
|
||||
class SMSChannel {
|
||||
-provider: string
|
||||
-rateLimit: int
|
||||
+send(notification, recipient) DeliveryAttempt
|
||||
+getStatus(attemptId) DeliveryStatus
|
||||
+validateRecipient(recipient) bool
|
||||
}
|
||||
|
||||
class PushChannel {
|
||||
-firebaseKey: string
|
||||
-apnsKey: string
|
||||
+send(notification, recipient) DeliveryAttempt
|
||||
+getStatus(attemptId) DeliveryStatus
|
||||
+validateRecipient(recipient) bool
|
||||
}
|
||||
|
||||
class WebhookChannel {
|
||||
-signingSecret: string
|
||||
-timeout: int
|
||||
+send(notification, recipient) DeliveryAttempt
|
||||
+getStatus(attemptId) DeliveryStatus
|
||||
+validateRecipient(recipient) bool
|
||||
}
|
||||
}
|
||||
|
||||
namespace Models {
|
||||
class Notification {
|
||||
+id: uuid
|
||||
+channel: string
|
||||
+subject: string
|
||||
+body: string
|
||||
+priority: string
|
||||
+createdAt: timestamp
|
||||
}
|
||||
|
||||
class Recipient {
|
||||
+id: uuid
|
||||
+email: string
|
||||
+phone: string
|
||||
+deviceTokens: List~string~
|
||||
+preferences: Map~string, bool~
|
||||
}
|
||||
|
||||
class DeliveryAttempt {
|
||||
+id: uuid
|
||||
+notificationId: uuid
|
||||
+recipientId: uuid
|
||||
+status: DeliveryStatus
|
||||
+attemptNumber: int
|
||||
+sentAt: timestamp
|
||||
}
|
||||
|
||||
class DeliveryStatus {
|
||||
<<enumeration>>
|
||||
QUEUED
|
||||
SENDING
|
||||
DELIVERED
|
||||
FAILED
|
||||
BOUNCED
|
||||
}
|
||||
}
|
||||
|
||||
NotificationService *-- NotificationQueue : contains
|
||||
NotificationService *-- ChannelRegistry : contains
|
||||
ChannelRegistry --> Channel : resolves
|
||||
|
||||
Channel <|.. EmailChannel : implements
|
||||
Channel <|.. SMSChannel : implements
|
||||
Channel <|.. PushChannel : implements
|
||||
Channel <|.. WebhookChannel : implements
|
||||
|
||||
Channel ..> Notification : receives
|
||||
Channel ..> Recipient : delivers to
|
||||
Channel ..> DeliveryAttempt : produces
|
||||
|
||||
DeliveryAttempt --> DeliveryStatus : has
|
||||
|
||||
style Channel fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
|
||||
style DeliveryStatus fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
|
||||
style NotificationService fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
|
||||
style NotificationQueue fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
|
||||
style ChannelRegistry fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
|
||||
style EmailChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
|
||||
style SMSChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
|
||||
style PushChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
|
||||
style WebhookChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
|
||||
style Notification fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
|
||||
style Recipient fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
|
||||
style DeliveryAttempt fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
|
||||
```
|
||||
|
||||
### Why this works
|
||||
|
||||
- **3 namespaces mirror architectural layers** — Core (orchestration), Channels (delivery implementations), Models (data). A developer can scan one namespace without reading the others.
|
||||
- **Color encodes the role** — purple for interfaces/enums, blue for core services, green for concrete implementations, gray for data models. The pattern is instantly recognizable.
|
||||
- **Relationship types are deliberate** — composition (`*--`) for "owns and manages", implementation (`<|..`) for "fulfills contract", dependency (`..>`) for "uses at runtime". Each arrow type carries meaning.
|
||||
Reference in New Issue
Block a user