675 lines
27 KiB
HTML
675 lines
27 KiB
HTML
|
|
<!DOCTYPE HTML>
|
||
|
|
<html lang="en" class="rust sidebar-visible" dir="ltr">
|
||
|
|
<head>
|
||
|
|
<!-- Book generated using mdBook -->
|
||
|
|
<meta charset="UTF-8">
|
||
|
|
<title>Use Cases - KOGRAL Documentation</title>
|
||
|
|
|
||
|
|
|
||
|
|
<!-- Custom HTML head -->
|
||
|
|
|
||
|
|
<meta name="description" content="Complete documentation for KOGRAL - Git-native knowledge graphs for developer teams">
|
||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
|
|
<meta name="theme-color" content="#ffffff">
|
||
|
|
|
||
|
|
<link rel="icon" href="../favicon.svg">
|
||
|
|
<link rel="shortcut icon" href="../favicon.png">
|
||
|
|
<link rel="stylesheet" href="../css/variables.css">
|
||
|
|
<link rel="stylesheet" href="../css/general.css">
|
||
|
|
<link rel="stylesheet" href="../css/chrome.css">
|
||
|
|
<link rel="stylesheet" href="../css/print.css" media="print">
|
||
|
|
|
||
|
|
<!-- Fonts -->
|
||
|
|
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
||
|
|
<link rel="stylesheet" href="../fonts/fonts.css">
|
||
|
|
|
||
|
|
<!-- Highlight.js Stylesheets -->
|
||
|
|
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
||
|
|
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
||
|
|
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
||
|
|
|
||
|
|
<!-- Custom theme stylesheets -->
|
||
|
|
|
||
|
|
|
||
|
|
<!-- Provide site root and default themes to javascript -->
|
||
|
|
<script>
|
||
|
|
const path_to_root = "../";
|
||
|
|
const default_light_theme = "rust";
|
||
|
|
const default_dark_theme = "navy";
|
||
|
|
</script>
|
||
|
|
<!-- Start loading toc.js asap -->
|
||
|
|
<script src="../toc.js"></script>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div id="mdbook-help-container">
|
||
|
|
<div id="mdbook-help-popup">
|
||
|
|
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
||
|
|
<div>
|
||
|
|
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
||
|
|
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
||
|
|
<p>Press <kbd>?</kbd> to show this help</p>
|
||
|
|
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div id="body-container">
|
||
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
|
|
<script>
|
||
|
|
try {
|
||
|
|
let theme = localStorage.getItem('mdbook-theme');
|
||
|
|
let sidebar = localStorage.getItem('mdbook-sidebar');
|
||
|
|
|
||
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||
|
|
}
|
||
|
|
|
||
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||
|
|
}
|
||
|
|
} catch (e) { }
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
||
|
|
<script>
|
||
|
|
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
||
|
|
let theme;
|
||
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
|
|
const html = document.documentElement;
|
||
|
|
html.classList.remove('rust')
|
||
|
|
html.classList.add(theme);
|
||
|
|
html.classList.add("js");
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
||
|
|
|
||
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
||
|
|
<script>
|
||
|
|
let sidebar = null;
|
||
|
|
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
||
|
|
if (document.body.clientWidth >= 1080) {
|
||
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
|
|
sidebar = sidebar || 'visible';
|
||
|
|
} else {
|
||
|
|
sidebar = 'hidden';
|
||
|
|
}
|
||
|
|
sidebar_toggle.checked = sidebar === 'visible';
|
||
|
|
html.classList.remove('sidebar-visible');
|
||
|
|
html.classList.add("sidebar-" + sidebar);
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
|
|
<!-- populated by js -->
|
||
|
|
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
||
|
|
<noscript>
|
||
|
|
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
||
|
|
</noscript>
|
||
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
||
|
|
<div class="sidebar-resize-indicator"></div>
|
||
|
|
</div>
|
||
|
|
</nav>
|
||
|
|
|
||
|
|
<div id="page-wrapper" class="page-wrapper">
|
||
|
|
|
||
|
|
<div class="page">
|
||
|
|
<div id="menu-bar-hover-placeholder"></div>
|
||
|
|
<div id="menu-bar" class="menu-bar sticky">
|
||
|
|
<div class="left-buttons">
|
||
|
|
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||
|
|
<i class="fa fa-bars"></i>
|
||
|
|
</label>
|
||
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||
|
|
<i class="fa fa-paint-brush"></i>
|
||
|
|
</button>
|
||
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||
|
|
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
||
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||
|
|
</ul>
|
||
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
||
|
|
<i class="fa fa-search"></i>
|
||
|
|
</button>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h1 class="menu-title">KOGRAL Documentation</h1>
|
||
|
|
|
||
|
|
<div class="right-buttons">
|
||
|
|
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
||
|
|
<i id="print-button" class="fa fa-print"></i>
|
||
|
|
</a>
|
||
|
|
<a href="https://github.com/your-org/knowledge-base" title="Git repository" aria-label="Git repository">
|
||
|
|
<i id="git-repository-button" class="fa fa-github"></i>
|
||
|
|
</a>
|
||
|
|
<a href="https://github.com/your-org/knowledge-base/edit/main/docs/./guides/use-cases.md" title="Suggest an edit" aria-label="Suggest an edit">
|
||
|
|
<i id="git-edit-button" class="fa fa-edit"></i>
|
||
|
|
</a>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<div id="search-wrapper" class="hidden">
|
||
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
||
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||
|
|
</form>
|
||
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
||
|
|
<ul id="searchresults">
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||
|
|
<script>
|
||
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||
|
|
});
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<div id="content" class="content">
|
||
|
|
<main>
|
||
|
|
<h1 id="use-cases"><a class="header" href="#use-cases">Use Cases</a></h1>
|
||
|
|
<p>Real-world scenarios showing how KOGRAL solves common development challenges.</p>
|
||
|
|
<h2 id="use-case-1-onboarding-new-team-members"><a class="header" href="#use-case-1-onboarding-new-team-members">Use Case 1: Onboarding New Team Members</a></h2>
|
||
|
|
<h3 id="problem"><a class="header" href="#problem">Problem</a></h3>
|
||
|
|
<p>New developer joins the team. Needs to understand:</p>
|
||
|
|
<ul>
|
||
|
|
<li>Why we chose SurrealDB over PostgreSQL</li>
|
||
|
|
<li>How error handling works in this project</li>
|
||
|
|
<li>What coding patterns we follow</li>
|
||
|
|
<li>Recent architectural decisions</li>
|
||
|
|
</ul>
|
||
|
|
<h3 id="solution-with-kogral"><a class="header" href="#solution-with-kogral">Solution with KOGRAL</a></h3>
|
||
|
|
<p><strong>Team lead</strong>:</p>
|
||
|
|
<pre><code class="language-bash"># Export project knowledge to Logseq for visual exploration
|
||
|
|
kb export logseq ~/onboarding-docs
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>New developer</strong> (with Claude Code):</p>
|
||
|
|
<pre><code>Summarize our architectural decisions from the last 6 months
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Claude</strong> (via MCP):</p>
|
||
|
|
<pre><code>Found 8 decisions:
|
||
|
|
|
||
|
|
1. **Use SurrealDB for Storage** (accepted, 3 months ago)
|
||
|
|
- Context: Need graph database for knowledge relationships
|
||
|
|
- Consequences: Better queries, additional infrastructure
|
||
|
|
|
||
|
|
2. **Adopt Rust for Core Logic** (accepted, 5 months ago)
|
||
|
|
- Context: Type safety and performance critical
|
||
|
|
- Consequences: Steeper learning curve, excellent reliability
|
||
|
|
|
||
|
|
... [6 more decisions]
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>New developer</strong>:</p>
|
||
|
|
<pre><code>What are our error handling guidelines?
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Claude</strong> (via <code>kb/get_guidelines</code>):</p>
|
||
|
|
<pre><code>## Rust Error Handling Guidelines
|
||
|
|
|
||
|
|
### Project Guidelines (priority: 150)
|
||
|
|
- Use thiserror for custom error types
|
||
|
|
- Never unwrap() in production
|
||
|
|
- Propagate with ? operator
|
||
|
|
|
||
|
|
### Shared Guidelines (priority: 50)
|
||
|
|
- Always use Result<T> for fallible operations
|
||
|
|
- Add context with .context()
|
||
|
|
|
||
|
|
[Links to full guideline documents]
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Result</strong>: New developer productive in days, not weeks.</p>
|
||
|
|
<hr />
|
||
|
|
<h2 id="use-case-2-architectural-decision-records-adr"><a class="header" href="#use-case-2-architectural-decision-records-adr">Use Case 2: Architectural Decision Records (ADR)</a></h2>
|
||
|
|
<h3 id="problem-1"><a class="header" href="#problem-1">Problem</a></h3>
|
||
|
|
<p>Team discussing whether to add Redis caching. Multiple opinions, need to document the decision for future reference.</p>
|
||
|
|
<h3 id="solution-with-kogral-1"><a class="header" href="#solution-with-kogral-1">Solution with KOGRAL</a></h3>
|
||
|
|
<p><strong>During meeting</strong>:</p>
|
||
|
|
<pre><code>Document decision: Add Redis caching for API responses
|
||
|
|
|
||
|
|
Context:
|
||
|
|
- Current database queries average 200ms
|
||
|
|
- 80% of queries are repeated within 5 minutes
|
||
|
|
- Need sub-50ms response times for user experience
|
||
|
|
|
||
|
|
Decision:
|
||
|
|
- Add Redis with 5-minute TTL for GET endpoints
|
||
|
|
- Cache invalidation on POST/PUT/DELETE
|
||
|
|
|
||
|
|
Consequences:
|
||
|
|
- ✅ Expected 80% reduction in database load
|
||
|
|
- ✅ Sub-50ms response times achieved
|
||
|
|
- ❌ Additional infrastructure (Redis server)
|
||
|
|
- ❌ Cache consistency challenges
|
||
|
|
- ❌ Debugging complexity increases
|
||
|
|
|
||
|
|
Status: proposed (pending infrastructure setup)
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Claude</strong> (creates ADR):</p>
|
||
|
|
<pre><code>Created: decision-add-redis-caching
|
||
|
|
Type: decision
|
||
|
|
Status: proposed
|
||
|
|
|
||
|
|
Added relationships:
|
||
|
|
- Relates to: note-performance-requirements
|
||
|
|
- Depends on: decision-use-docker-compose (infrastructure)
|
||
|
|
|
||
|
|
Decision documented and linked to related knowledge.
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Two months later</strong>, someone asks "Why Redis?":</p>
|
||
|
|
<pre><code>kb show decision-add-redis-caching
|
||
|
|
</code></pre>
|
||
|
|
<p>Full context available instantly.</p>
|
||
|
|
<hr />
|
||
|
|
<h2 id="use-case-3-pattern-library"><a class="header" href="#use-case-3-pattern-library">Use Case 3: Pattern Library</a></h2>
|
||
|
|
<h3 id="problem-2"><a class="header" href="#problem-2">Problem</a></h3>
|
||
|
|
<p>Team solves the same problems repeatedly:</p>
|
||
|
|
<ul>
|
||
|
|
<li>How to structure error types</li>
|
||
|
|
<li>Database connection patterns</li>
|
||
|
|
<li>Testing strategies</li>
|
||
|
|
</ul>
|
||
|
|
<p>Each developer rediscovers solutions.</p>
|
||
|
|
<h3 id="solution-with-kogral-2"><a class="header" href="#solution-with-kogral-2">Solution with KOGRAL</a></h3>
|
||
|
|
<p><strong>First time</strong> solving error handling:</p>
|
||
|
|
<pre><code class="language-bash">kb add pattern "Error Handling with thiserror" \
|
||
|
|
--tags rust,error-handling,pattern \
|
||
|
|
--content "$(cat docs/error-pattern.md)"
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Next time</strong> someone needs error handling:</p>
|
||
|
|
<pre><code>I'm implementing a new module with errors. What's our standard pattern?
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Claude</strong> (via <code>kogral/search</code>):</p>
|
||
|
|
<pre><code>Found pattern: Error Handling with thiserror
|
||
|
|
|
||
|
|
## Pattern: Error Handling with thiserror
|
||
|
|
|
||
|
|
### Problem
|
||
|
|
Need structured, type-safe error handling with good error messages.
|
||
|
|
|
||
|
|
### Solution
|
||
|
|
```rust
|
||
|
|
use thiserror::Error;
|
||
|
|
|
||
|
|
#[derive(Error, Debug)]
|
||
|
|
pub enum ModuleError {
|
||
|
|
#[error("Database connection failed: {0}")]
|
||
|
|
Database(#[from] sqlx::Error),
|
||
|
|
|
||
|
|
#[error("Validation failed: {0}")]
|
||
|
|
Validation(String),
|
||
|
|
}
|
||
|
|
</code></pre>
|
||
|
|
<h3 id="usage"><a class="header" href="#usage">Usage</a></h3>
|
||
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||
|
|
</span><span class="boring">fn main() {
|
||
|
|
</span>fn do_work() -> Result<(), ModuleError> {
|
||
|
|
let conn = connect_db()?; // Auto-converts via #[from]
|
||
|
|
validate_input()?;
|
||
|
|
Ok(())
|
||
|
|
}
|
||
|
|
<span class="boring">}</span></code></pre></pre>
|
||
|
|
<p>[Full pattern with examples]</p>
|
||
|
|
<p>Would you like me to create a new error module following this pattern?</p>
|
||
|
|
<pre><code>
|
||
|
|
**Result**: Consistent error handling across codebase, zero time wasted rediscovering patterns.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Use Case 4: Daily Development Journal
|
||
|
|
|
||
|
|
### Problem
|
||
|
|
|
||
|
|
Developer wants to track:
|
||
|
|
- What they worked on each day
|
||
|
|
- Blockers encountered
|
||
|
|
- Solutions discovered
|
||
|
|
- Ideas for future work
|
||
|
|
|
||
|
|
### Solution with KOGRAL
|
||
|
|
|
||
|
|
**End of each day**:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
kb add journal "2026-01-17" --content "
|
||
|
|
## Progress
|
||
|
|
- Implemented user authentication
|
||
|
|
- Fixed race condition in cache layer
|
||
|
|
- Started work on API rate limiting
|
||
|
|
|
||
|
|
## Blockers
|
||
|
|
- SurrealDB migration tool not working with nested objects
|
||
|
|
- Need to discuss API versioning strategy with team
|
||
|
|
|
||
|
|
## Learnings
|
||
|
|
- tokio::select! is perfect for timeout patterns
|
||
|
|
- serde_json::Value useful for dynamic JSON handling
|
||
|
|
|
||
|
|
## Tomorrow
|
||
|
|
- Finish rate limiting implementation
|
||
|
|
- Review PR #234
|
||
|
|
- Team meeting: discuss API versioning
|
||
|
|
"
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>With Claude Code</strong> (even easier):</p>
|
||
|
|
<pre><code>End of day journal:
|
||
|
|
|
||
|
|
Implemented authentication, fixed cache race condition, started rate limiting.
|
||
|
|
Blocked on SurrealDB migrations and need API versioning discussion.
|
||
|
|
Learned about tokio::select! for timeouts.
|
||
|
|
Tomorrow: finish rate limiting, review PR #234, versioning meeting.
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Claude</strong> (creates journal entry):</p>
|
||
|
|
<pre><code>Created journal entry: 2026-01-17
|
||
|
|
|
||
|
|
Tags auto-detected: authentication, cache, rate-limiting, surrealdb
|
||
|
|
|
||
|
|
Linked to:
|
||
|
|
- pattern-timeout-handling (implements)
|
||
|
|
- decision-use-surrealdb (relates_to)
|
||
|
|
|
||
|
|
Journal entry saved.
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Two weeks later</strong> (forgot how you solved that race condition):</p>
|
||
|
|
<pre><code>How did I fix the cache race condition?
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Claude</strong> (semantic search):</p>
|
||
|
|
<pre><code>From your journal entry on 2026-01-17:
|
||
|
|
|
||
|
|
"Fixed race condition in cache layer by using DashMap instead of
|
||
|
|
RwLock<HashMap>. DashMap provides lock-free concurrent access."
|
||
|
|
|
||
|
|
[Link to full journal entry]
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Result</strong>: Development history preserved, solutions easy to recall.</p>
|
||
|
|
<hr />
|
||
|
|
<h2 id="use-case-5-code-review-preparation"><a class="header" href="#use-case-5-code-review-preparation">Use Case 5: Code Review Preparation</a></h2>
|
||
|
|
<h3 id="problem-3"><a class="header" href="#problem-3">Problem</a></h3>
|
||
|
|
<p>Preparing for code review. Need to:</p>
|
||
|
|
<ul>
|
||
|
|
<li>Document why certain decisions were made</li>
|
||
|
|
<li>Link implementation to requirements</li>
|
||
|
|
<li>Explain trade-offs to reviewers</li>
|
||
|
|
</ul>
|
||
|
|
<h3 id="solution-with-kogral-3"><a class="header" href="#solution-with-kogral-3">Solution with KOGRAL</a></h3>
|
||
|
|
<p><strong>Before creating PR</strong>:</p>
|
||
|
|
<pre><code>I just implemented the caching layer.
|
||
|
|
Add a note documenting the implementation and link it to our caching decision.
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Claude</strong> (via <code>kb/add_note</code> + <code>kb/link</code>):</p>
|
||
|
|
<pre><code>Created note: note-caching-layer-implementation
|
||
|
|
|
||
|
|
Content:
|
||
|
|
# Caching Layer Implementation
|
||
|
|
|
||
|
|
## Approach
|
||
|
|
- Redis with 5-minute TTL
|
||
|
|
- Cache-aside pattern
|
||
|
|
- Invalidation on mutations
|
||
|
|
|
||
|
|
## Trade-offs
|
||
|
|
- Chose simplicity over advanced features (no LRU eviction)
|
||
|
|
- 5-minute TTL balances freshness vs cache hit rate
|
||
|
|
- Cache-aside pattern chosen over write-through (simpler)
|
||
|
|
|
||
|
|
## Testing
|
||
|
|
- Unit tests for cache logic
|
||
|
|
- Integration tests with real Redis
|
||
|
|
- Load test: 1000 req/s sustained
|
||
|
|
|
||
|
|
Links:
|
||
|
|
- Implements: decision-add-redis-caching
|
||
|
|
- Follows: pattern-cache-aside
|
||
|
|
- Tests: guideline-integration-testing
|
||
|
|
|
||
|
|
Note added and linked to decision-add-redis-caching.
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>In PR description</strong>:</p>
|
||
|
|
<pre><code class="language-markdown">## Implementation
|
||
|
|
|
||
|
|
Implements caching layer per decision-add-redis-caching.
|
||
|
|
|
||
|
|
See note-caching-layer-implementation for detailed rationale.
|
||
|
|
|
||
|
|
## Trade-offs
|
||
|
|
|
||
|
|
[Copy from note]
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Reviewers</strong>:</p>
|
||
|
|
<pre><code>kb show decision-add-redis-caching
|
||
|
|
kb show note-caching-layer-implementation
|
||
|
|
</code></pre>
|
||
|
|
<p>Full context available, review focuses on code quality not "why this approach?"</p>
|
||
|
|
<hr />
|
||
|
|
<h2 id="use-case-6-cross-project-guidelines"><a class="header" href="#use-case-6-cross-project-guidelines">Use Case 6: Cross-Project Guidelines</a></h2>
|
||
|
|
<h3 id="problem-4"><a class="header" href="#problem-4">Problem</a></h3>
|
||
|
|
<p>Organization has 10 projects. Each should follow:</p>
|
||
|
|
<ul>
|
||
|
|
<li>Same Rust error handling patterns</li>
|
||
|
|
<li>Same security guidelines</li>
|
||
|
|
<li>Same testing standards</li>
|
||
|
|
</ul>
|
||
|
|
<p>Currently: duplicated wikis, inconsistent practices.</p>
|
||
|
|
<h3 id="solution-with-kogral-4"><a class="header" href="#solution-with-kogral-4">Solution with KOGRAL</a></h3>
|
||
|
|
<p><strong>Setup shared KOGRAL</strong>:</p>
|
||
|
|
<pre><code class="language-bash"># Create organization-wide shared KB
|
||
|
|
mkdir -p ~/org/.kogral-shared
|
||
|
|
cd ~/org/.kogral-shared
|
||
|
|
kb init --name "Organization Guidelines"
|
||
|
|
|
||
|
|
# Add shared guidelines
|
||
|
|
kb add guideline "Rust Error Handling" \
|
||
|
|
--language rust \
|
||
|
|
--category error-handling \
|
||
|
|
--content "$(cat org-rust-errors.md)"
|
||
|
|
|
||
|
|
kb add guideline "Security Best Practices" \
|
||
|
|
--category security \
|
||
|
|
--content "$(cat org-security.md)"
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>In each project</strong>:</p>
|
||
|
|
<pre><code class="language-nickel"># project/.kogral/config.ncl
|
||
|
|
{
|
||
|
|
inheritance = {
|
||
|
|
base = "~/org/.kogral-shared",
|
||
|
|
priority = 100, # Project overrides shared
|
||
|
|
},
|
||
|
|
}
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Developer in Project A</strong>:</p>
|
||
|
|
<pre><code>What are our error handling guidelines?
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Claude</strong> (via <code>kb/get_guidelines</code> with inheritance):</p>
|
||
|
|
<pre><code>## Rust Error Handling Guidelines
|
||
|
|
|
||
|
|
### Shared Guidelines (priority: 50)
|
||
|
|
From ~/org/.kogral-shared:
|
||
|
|
- Use thiserror for custom errors
|
||
|
|
- Never unwrap() in production
|
||
|
|
- Always propagate with ?
|
||
|
|
|
||
|
|
### Project Guidelines (priority: 100)
|
||
|
|
From project .kogral/:
|
||
|
|
- Additionally: log all errors with tracing
|
||
|
|
- Use anyhow for application-level errors
|
||
|
|
|
||
|
|
[Combined effective guidelines]
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Result</strong>:</p>
|
||
|
|
<ul>
|
||
|
|
<li>Consistent practices across organization</li>
|
||
|
|
<li>Projects can specialize where needed</li>
|
||
|
|
<li>Single source of truth for shared knowledge</li>
|
||
|
|
</ul>
|
||
|
|
<hr />
|
||
|
|
<h2 id="use-case-7-bug-investigation"><a class="header" href="#use-case-7-bug-investigation">Use Case 7: Bug Investigation</a></h2>
|
||
|
|
<h3 id="problem-5"><a class="header" href="#problem-5">Problem</a></h3>
|
||
|
|
<p>Bug in production. Developer needs to:</p>
|
||
|
|
<ul>
|
||
|
|
<li>Understand relevant decisions</li>
|
||
|
|
<li>Find related code patterns</li>
|
||
|
|
<li>Check if similar issues were solved before</li>
|
||
|
|
</ul>
|
||
|
|
<h3 id="solution-with-kogral-5"><a class="header" href="#solution-with-kogral-5">Solution with KOGRAL</a></h3>
|
||
|
|
<p><strong>Developer</strong>:</p>
|
||
|
|
<pre><code>We have a race condition in the cache layer.
|
||
|
|
What past decisions or patterns might be relevant?
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Claude</strong> (semantic search):</p>
|
||
|
|
<pre><code>Found 4 relevant items:
|
||
|
|
|
||
|
|
1. **Decision: Use DashMap for Concurrent Access** (accepted, 1 month ago)
|
||
|
|
"Chose DashMap over RwLock<HashMap> to avoid race conditions in cache"
|
||
|
|
|
||
|
|
2. **Pattern: Safe Concurrent Cache Access**
|
||
|
|
"Always use lock-free data structures for high-contention caches"
|
||
|
|
|
||
|
|
3. **Note: Cache Race Condition Fix** (from 2026-01-17 journal)
|
||
|
|
"Fixed race in cache by switching to DashMap"
|
||
|
|
|
||
|
|
4. **Guideline: Concurrency Safety**
|
||
|
|
"Use atomic operations and lock-free structures where possible"
|
||
|
|
|
||
|
|
It looks like we've seen this before! Check the journal entry from 2026-01-17.
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Developer reads journal</strong>:</p>
|
||
|
|
<pre><code class="language-bash">kb show journal-2026-01-17
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Finds</strong>:</p>
|
||
|
|
<ul>
|
||
|
|
<li>Exact same issue</li>
|
||
|
|
<li>Solution: switch to DashMap</li>
|
||
|
|
<li>Code example included</li>
|
||
|
|
<li>Performance benchmarks</li>
|
||
|
|
</ul>
|
||
|
|
<p><strong>Applies fix</strong> in 10 minutes instead of 2 hours of debugging.</p>
|
||
|
|
<hr />
|
||
|
|
<h2 id="use-case-8-api-design-collaboration"><a class="header" href="#use-case-8-api-design-collaboration">Use Case 8: API Design Collaboration</a></h2>
|
||
|
|
<h3 id="problem-6"><a class="header" href="#problem-6">Problem</a></h3>
|
||
|
|
<p>Team discussing new API design. Multiple approaches:</p>
|
||
|
|
<ul>
|
||
|
|
<li>REST vs GraphQL</li>
|
||
|
|
<li>Versioning strategy</li>
|
||
|
|
<li>Authentication method</li>
|
||
|
|
</ul>
|
||
|
|
<p>Need to capture discussion and decision.</p>
|
||
|
|
<h3 id="solution-with-kogral-6"><a class="header" href="#solution-with-kogral-6">Solution with KOGRAL</a></h3>
|
||
|
|
<p><strong>During design meeting</strong> (using Claude Code):</p>
|
||
|
|
<pre><code>We're designing the new API. Let me capture this discussion:
|
||
|
|
|
||
|
|
Approaches discussed:
|
||
|
|
1. REST with versioned endpoints (/v1/, /v2/)
|
||
|
|
2. GraphQL with schema versioning
|
||
|
|
3. gRPC for internal services
|
||
|
|
|
||
|
|
Team consensus:
|
||
|
|
- REST for public API (easier for partners)
|
||
|
|
- GraphQL for internal admin tools (flexibility)
|
||
|
|
- gRPC for service-to-service (performance)
|
||
|
|
|
||
|
|
Create a decision record for each, linking them together.
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Claude</strong> (creates 3 linked ADRs):</p>
|
||
|
|
<pre><code>Created 3 decisions:
|
||
|
|
|
||
|
|
1. decision-rest-public-api
|
||
|
|
Status: accepted
|
||
|
|
Context: Public API needs broad compatibility
|
||
|
|
Decision: REST with /v1/, /v2/ versioning
|
||
|
|
|
||
|
|
2. decision-graphql-admin
|
||
|
|
Status: accepted
|
||
|
|
Context: Admin tools need flexible queries
|
||
|
|
Decision: GraphQL with schema evolution
|
||
|
|
|
||
|
|
3. decision-grpc-internal
|
||
|
|
Status: accepted
|
||
|
|
Context: Service-to-service needs performance
|
||
|
|
Decision: gRPC with protobuf
|
||
|
|
|
||
|
|
Linked:
|
||
|
|
decision-rest-public-api --[relates_to]--> decision-graphql-admin
|
||
|
|
decision-rest-public-api --[relates_to]--> decision-grpc-internal
|
||
|
|
decision-graphql-admin --[relates_to]--> decision-grpc-internal
|
||
|
|
|
||
|
|
All decisions documented and interconnected.
|
||
|
|
</code></pre>
|
||
|
|
<p><strong>Two months later</strong>, someone asks "Why REST not GraphQL for public API?":</p>
|
||
|
|
<pre><code class="language-bash">kb show decision-rest-public-api
|
||
|
|
</code></pre>
|
||
|
|
<p>Full context preserved, including relationship to GraphQL decision.</p>
|
||
|
|
<hr />
|
||
|
|
<h2 id="summary"><a class="header" href="#summary">Summary</a></h2>
|
||
|
|
<p>Knowledge Base excels at:</p>
|
||
|
|
<p>✅ <strong>Onboarding</strong>: Historical context instantly available
|
||
|
|
✅ <strong>Decision Making</strong>: ADRs preserve rationale
|
||
|
|
✅ <strong>Pattern Reuse</strong>: Solutions documented once, used forever
|
||
|
|
✅ <strong>Daily Tracking</strong>: Development journal with semantic search
|
||
|
|
✅ <strong>Code Review</strong>: Implementation rationale linked to decisions
|
||
|
|
✅ <strong>Cross-Project</strong>: Shared guidelines with project overrides
|
||
|
|
✅ <strong>Bug Investigation</strong>: Past solutions easily discovered
|
||
|
|
✅ <strong>Collaboration</strong>: Discussions captured and interconnected</p>
|
||
|
|
<p><strong>Common Theme</strong>: Knowledge captured during work, queryable when needed, connected to related concepts.</p>
|
||
|
|
<hr />
|
||
|
|
<h2 id="next-steps"><a class="header" href="#next-steps">Next Steps</a></h2>
|
||
|
|
<ul>
|
||
|
|
<li><strong>Start simple</strong>: <a href="quickstart.html">Quick Start Guide</a></li>
|
||
|
|
<li><strong>Integrate AI</strong>: <a href="../apps/mcp-quickguide.html">MCP Quick Guide</a></li>
|
||
|
|
<li><strong>Advanced features</strong>: <a href="../config/overview.html">Configuration Reference</a></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
</main>
|
||
|
|
|
||
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
|
|
<!-- Mobile navigation buttons -->
|
||
|
|
<a rel="prev" href="../guides/daily-workflows.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
|
|
<i class="fa fa-angle-left"></i>
|
||
|
|
</a>
|
||
|
|
|
||
|
|
<a rel="next prefetch" href="../guides/best-practices.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
|
|
<i class="fa fa-angle-right"></i>
|
||
|
|
</a>
|
||
|
|
|
||
|
|
<div style="clear: both"></div>
|
||
|
|
</nav>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||
|
|
<a rel="prev" href="../guides/daily-workflows.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
|
|
<i class="fa fa-angle-left"></i>
|
||
|
|
</a>
|
||
|
|
|
||
|
|
<a rel="next prefetch" href="../guides/best-practices.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
|
|
<i class="fa fa-angle-right"></i>
|
||
|
|
</a>
|
||
|
|
</nav>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<script>
|
||
|
|
window.playground_copyable = true;
|
||
|
|
</script>
|
||
|
|
|
||
|
|
|
||
|
|
<script src="../elasticlunr.min.js"></script>
|
||
|
|
<script src="../mark.min.js"></script>
|
||
|
|
<script src="../searcher.js"></script>
|
||
|
|
|
||
|
|
<script src="../clipboard.min.js"></script>
|
||
|
|
<script src="../highlight.js"></script>
|
||
|
|
<script src="../book.js"></script>
|
||
|
|
|
||
|
|
<!-- Custom JS scripts -->
|
||
|
|
|
||
|
|
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|