oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 7 Packages Projects Releases Wiki Activity
Files
b43b3aa3da4382f46718985fa37dfd37a31ed399
aitbc/website/docs/flowchart.html
aitbc b43b3aa3da fix: update website documentation to reflect current port assignments 
Website Documentation Port Update - Complete:
✅ WEBSITE DIRECTORY UPDATED: All documentation updated to current port assignments
- website/docs/flowchart.html: Updated from old 18000/18001 ports to current 8000/8010/8006
- website/docs/api.html: Updated development URL from 18000 to 8000
- Reason: Website documentation now reflects actual AITBC service ports

✅ PORT UPDATES COMPLETED:
🔧 Core Services:
  - Coordinator API: 18000 → 8000 ✅
  - Blockchain RPC: 26657 → 8006 ✅

🚀 AI/Agent/GPU Services:
  - GPU Service/Miner: 18001 → 8010 ✅

✅ FLOWCHART DOCUMENTATION UPDATED:
📊 Architecture Diagram: Port flow updated to current assignments
🌐 Environment Variables: AITBC_URL updated to 8000
📡 HTTP Requests: All Host headers updated to correct ports
⏱️ Timeline: Message flow updated with current ports
📋 Service Table: Port assignments table updated

✅ API DOCUMENTATION UPDATED:
🔗 Base URL: Development URL updated to 8000
📚 Documentation: References now point to correct services

✅ WEBSITE FUNCTIONALITY:
✅ Documentation Accuracy: All docs show correct service ports
✅ Developer Experience: API docs use actual service endpoints
✅ Architecture Clarity: Flowchart reflects current system design
✅ Consistency: All website references match service configs

✅ SYSTEM-WIDE SYNCHRONIZATION:
✅ Health Check Script: ✅ Matches service configurations
✅ Service Files: ✅ All updated to match health check
✅ Documentation: ✅ Reflects actual port assignments
✅ Apps Directory: ✅ All hardcoded references updated
✅ CLI Directory: ✅ All commands updated to current ports
✅ Scripts Directory: ✅ All scripts updated to current ports
✅ Tests Directory: ✅ All tests verified and documented
✅ Website Directory: ✅ All documentation updated to current ports
✅ Integration Layer: ✅ Service endpoints synchronized

✅ PORT MAPPING COMPLETED:
✅ Old Architecture: 18000/18001 (legacy) → Current Architecture: 8000/8010/8006
✅ Documentation Consistency: Website matches actual service deployment
✅ Developer Resources: API docs and flowchart are accurate
✅ User Experience: Website visitors see correct port information

✅ FINAL VERIFICATION:
✅ All Website References: Updated to current port assignments
✅ Documentation Accuracy: Complete consistency with service configs
✅ Developer Resources: API and architecture docs are correct
✅ User Experience: Website provides accurate service information

RESULT: Successfully updated all website documentation to reflect the current AITBC port assignments. The website now provides accurate documentation that matches the actual service configuration, ensuring developers and users have correct information about service endpoints and architecture.
2026-03-30 18:42:20 +02:00

492 lines
21 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en" data-theme="dark">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>System Flow - AITBC Documentation</title>
<link rel="stylesheet" href="css/docs.css">
<link rel="stylesheet" href="/assets/css/site-header.css">
<link rel="preload" href="/assets/css/font-awesome.min.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
<noscript><link rel="stylesheet" href="/assets/css/font-awesome.min.css"></noscript>
<!-- Font Awesome CDN fallback -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css" crossorigin="anonymous" media="print" onload="this.media='all'; this.onload=null;">
</head>
<body>
<div data-global-header></div>
<main>
<div class="container">
<!-- Breadcrumb -->
<div class="breadcrumb">
<a href="index.html">Documentation</a>
<span>›</span>
<span>System Flow</span>
</div>
<!-- Back Button -->
<a href="index.html" class="back-button">
<i class="fas fa-arrow-left"></i>
Back to Documentation
</a>
<!-- Header -->
<div class="doc-header">
<h1><i class="fas fa-sitemap"></i> AITBC System Flow</h1>
<p>Complete flow of a job submission through the CLI client, detailing each system component, message, RPC call, and port involved.</p>
</div>
<!-- Overview Diagram -->
<section class="content-section">
<h2>Overview Diagram</h2>
<div style="background: #f8fafc; padding: 2rem; border-radius: 8px; overflow-x: auto;">
<div style="display: flex; align-items: center; gap: 1rem; margin-bottom: 1rem; font-family: monospace;">
<div style="background: #3b82f6; color: white; padding: 0.5rem 1rem; border-radius: 4px; white-space: nowrap;">CLI Wrapper</div>
<div style="color: #64748b;">→</div>
<div style="background: #10b981; color: white; padding: 0.5rem 1rem; border-radius: 4px; white-space: nowrap;">Client Python</div>
<div style="color: #64748b;">→</div>
<div style="background: #f59e0b; color: white; padding: 0.5rem 1rem; border-radius: 4px; white-space: nowrap;">Coordinator</div>
<div style="color: #64748b;">→</div>
<div style="background: #ef4444; color: white; padding: 0.5rem 1rem; border-radius: 4px; white-space: nowrap;">Blockchain</div>
<div style="color: #64748b;">→</div>
<div style="background: #8b5cf6; color: white; padding: 0.5rem 1rem; border-radius: 4px; white-space: nowrap;">Miner</div>
<div style="color: #64748b;">→</div>
<div style="background: #06b6d4; color: white; padding: 0.5rem 1rem; border-radius: 4px; white-space: nowrap;">Ollama</div>
</div>
<div style="font-size: 0.85rem; color: #64748b; text-align: center; margin-top: 1rem;">
<div>(aitbc-cli.sh) → (client.py) → (port 8000) → (RPC:8006) → (port 8010) → (port 11434)</div>
</div>
</div>
<h3 style="margin-top: 2rem;">Component Interactions</h3>
<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 1.5rem; margin-top: 1.5rem;">
<div style="background: #f1f5f9; padding: 1.5rem; border-radius: 8px; border-left: 4px solid #3b82f6;">
<h4 style="margin-top: 0; color: #1e40af;">1. Job Submission</h4>
<p style="margin-bottom: 0; color: #475569;">User submits CLI command → Python client formats request → HTTP POST to Coordinator</p>
</div>
<div style="background: #f1f5f9; padding: 1.5rem; border-radius: 8px; border-left: 4px solid #f59e0b;">
<h4 style="margin-top: 0; color: #92400e;">2. Job Processing</h4>
<p style="margin-bottom: 0; color: #475569;">Coordinator validates → Creates blockchain transaction → Queues for miner</p>
</div>
<div style="background: #f1f5f9; padding: 1.5rem; border-radius: 8px; border-left: 4px solid #8b5cf6;">
<h4 style="margin-top: 0; color: #5b21b6;">3. AI Inference</h4>
<p style="margin-bottom: 0; color: #475569;">Miner receives job → Sends to Ollama → Processes on GPU → Returns result</p>
</div>
<div style="background: #f1f5f9; padding: 1.5rem; border-radius: 8px; border-left: 4px solid #ef4444;">
<h4 style="margin-top: 0; color: #991b1b;">4. Verification</h4>
<p style="margin-bottom: 0; color: #475569;">Result verified → Receipt generated → Recorded on blockchain → Client notified</p>
</div>
</div>
</section>
<!-- Detailed Flow Sequence -->
<section class="content-section">
<h2>Detailed Flow Sequence</h2>
<h3>1. CLI Wrapper Execution</h3>
<p><strong>User Command:</strong></p>
<pre><code>./scripts/aitbc-cli.sh submit inference --prompt "What is machine learning?" --model llama3.2:latest</code></pre>
<p><strong>Internal Process:</strong></p>
<ol>
<li>Bash script (<span class="inline-code">aitbc-cli.sh</span>) parses arguments</li>
<li>Sets environment variables:
<ul>
<li><span class="inline-code">AITBC_URL=http://127.0.0.1:8000</span></li>
<li><span class="inline-code">CLIENT_KEY=${CLIENT_API_KEY}</span></li>
</ul>
</li>
<li>Calls Python client: <span class="inline-code">python3 cli/client.py --url $AITBC_URL --api-key $CLIENT_KEY submit inference --prompt "..."</span></li>
</ol>
<h3>2. Python Client Processing</h3>
<p><strong>File:</strong> <span class="inline-code">/cli/client.py</span></p>
<p><strong>Steps:</strong></p>
<ol>
<li>Parse command-line arguments</li>
<li>Prepare job submission payload:
<pre><code>{
"type": "inference",
"prompt": "What is machine learning?",
"model": "llama3.2:latest",
"client_key": "${CLIENT_API_KEY}",
"timestamp": "2025-01-29T14:50:00Z"
}</code></pre>
</li>
</ol>
<h3>3. Coordinator API Call</h3>
<div class="http-request">
<h4>HTTP Request:</h4>
<pre><code>POST /v1/jobs
Host: 127.0.0.1:8000
Content-Type: application/json
X-Api-Key: ${CLIENT_API_KEY}
{
"type": "inference",
"prompt": "What is machine learning?",
"model": "llama3.2:latest"
}</code></pre>
</div>
<p><strong>Coordinator Service (Port 8000):</strong></p>
<ol>
<li>Receives HTTP request</li>
<li>Validates API key and job parameters</li>
<li>Generates unique job ID: <span class="inline-code">job_123456</span></li>
<li>Creates job record in database</li>
<li>Returns initial response:
<pre><code>{
"job_id": "job_123456",
"status": "pending",
"submitted_at": "2025-01-29T14:50:01Z"
}</code></pre>
</li>
</ol>
<h3>4. Blockchain Transaction</h3>
<p><strong>Coordinator → Blockchain Node (RPC Port 26657):</strong></p>
<ol>
<li>Coordinator creates blockchain transaction:
<pre><code>{
"type": "submit_job",
"job_id": "job_123456",
"client": "${CLIENT_API_KEY}",
"payload_hash": "abc123...",
"reward": "100aitbc"
}</code></pre>
</li>
<li>RPC Call to blockchain node:
<pre><code>curl -X POST http://127.0.0.1:26657 \
-d '{
"jsonrpc": "2.0",
"method": "broadcast_tx_sync",
"params": {"tx": "base64_encoded_transaction"}
}'</code></pre>
</li>
<li>Blockchain validates and includes transaction in next block</li>
<li>Transaction hash returned: <span class="inline-code">0xdef456...</span></li>
</ol>
<h3>5. Job Queue and Miner Assignment</h3>
<p><strong>Coordinator Internal Processing:</strong></p>
<ol>
<li>Job added to pending queue (Redis/Database)</li>
<li>Miner selection algorithm runs:
<ul>
<li>Check available miners</li>
<li>Select based on stake, reputation, capacity</li>
</ul>
</li>
<li>Selected miner: <span class="inline-code">${MINER_API_KEY}</span></li>
</ol>
<div class="http-request">
<h4>Coordinator → Miner (Port 8010):</h4>
<pre><code>POST /v1/jobs/assign
Host: 127.0.0.1:8010
Content-Type: application/json
X-Api-Key: ${ADMIN_API_KEY}
{
"job_id": "job_123456",
"job_data": {
"type": "inference",
"prompt": "What is machine learning?",
"model": "llama3.2:latest"
},
"reward": "100aitbc"
}</code></pre>
</div>
<h3>6. Miner Processing</h3>
<p><strong>Miner Daemon (Port 18001):</strong></p>
<ol>
<li>Receives job assignment</li>
<li>Updates job status to <span class="inline-code">running</span></li>
<li>Notifies coordinator:
<pre><code>POST /v1/jobs/job_123456/status
{"status": "running", "started_at": "2025-01-29T14:50:05Z"}</code></pre>
</li>
</ol>
<h3>7. Ollama Inference Request</h3>
<div class="http-request">
<h4>Miner → Ollama Server (Port 11434):</h4>
<pre><code>POST /api/generate
Host: 127.0.0.1:11434
Content-Type: application/json
{
"model": "llama3.2:latest",
"prompt": "What is machine learning?",
"stream": false,
"options": {
"temperature": 0.7,
"num_predict": 500
}
}</code></pre>
</div>
<p><strong>Ollama Processing:</strong></p>
<ol>
<li>Loads model into GPU memory</li>
<li>Processes prompt through neural network</li>
<li>Generates response text</li>
<li>Returns result:
<pre><code>{
"model": "llama3.2:latest",
"response": "Machine learning is a subset of artificial intelligence...",
"done": true,
"total_duration": 12500000000,
"prompt_eval_count": 15,
"eval_count": 150
}</code></pre>
</li>
</ol>
<h3>8. Result Submission to Coordinator</h3>
<div class="http-request">
<h4>Miner → Coordinator (Port 8000):</h4>
<pre><code>POST /v1/jobs/job_123456/complete
Host: 127.0.0.1:8000
Content-Type: application/json
X-Miner-Key: ${MINER_API_KEY}
{
"job_id": "job_123456",
"result": "Machine learning is a subset of artificial intelligence...",
"metrics": {
"compute_time": 12.5,
"tokens_generated": 150,
"gpu_utilization": 0.85
},
"proof": {
"hash": "hash_of_result",
"signature": "miner_signature"
}
}</code></pre>
</div>
<h3>9. Receipt Generation</h3>
<p><strong>Coordinator Processing:</strong></p>
<ol>
<li>Verifies miner's proof</li>
<li>Calculates payment: <span class="inline-code">12.5 seconds × 0.02 AITBC/second = 0.25 AITBC</span></li>
<li>Creates receipt:
<pre><code>{
"receipt_id": "receipt_789",
"job_id": "job_123456",
"client": "${CLIENT_API_KEY}",
"miner": "${MINER_API_KEY}",
"amount_paid": "0.25aitbc",
"result_hash": "hash_of_result",
"block_height": 12345,
"timestamp": "2025-01-29T14:50:18Z"
}</code></pre>
</li>
</ol>
<h3>10. Blockchain Receipt Recording</h3>
<pre><code>Coordinator → Blockchain (RPC Port 26657):
{
"type": "record_receipt",
"receipt": {
"receipt_id": "receipt_789",
"job_id": "job_123456",
"payment": "0.25aitbc"
}
}</code></pre>
<h3>11. Client Polling for Result</h3>
<p><strong>CLI Client Status Check:</strong></p>
<pre><code>./scripts/aitbc-cli.sh status job_123456</code></pre>
<div class="http-request">
<h4>HTTP Request:</h4>
<pre><code>GET /v1/jobs/job_123456
Host: 127.0.0.1:8000
X-Api-Key: ${CLIENT_API_KEY}</code></pre>
<h4>Response:</h4>
<pre><code>{
"job_id": "job_123456",
"status": "completed",
"result": "Machine learning is a subset of artificial intelligence...",
"receipt_id": "receipt_789",
"completed_at": "2025-01-29T14:50:18Z"
}</code></pre>
</div>
<h3>12. Final Output to User</h3>
<p><strong>CLI displays:</strong></p>
<pre><code>Job ID: job_123456
Status: completed
Result: Machine learning is a subset of artificial intelligence...
Receipt: receipt_789
Completed in: 17 seconds
Cost: 0.25 AITBC</code></pre>
</section>
<!-- System Components Summary -->
<section class="content-section">
<h2>System Components Summary</h2>
<table>
<thead>
<tr>
<th>Component</th>
<th>Port</th>
<th>Protocol</th>
<th>Responsibility</th>
</tr>
</thead>
<tbody>
<tr>
<td>CLI Wrapper</td>
<td>N/A</td>
<td>Bash</td>
<td>User interface, argument parsing</td>
</tr>
<tr>
<td>Client Python</td>
<td>N/A</td>
<td>Python</td>
<td>HTTP client, job formatting</td>
</tr>
<tr>
<td>Coordinator</td>
<td>8000</td>
<td>HTTP/REST</td>
<td>Job management, API gateway</td>
</tr>
<tr>
<td>Blockchain Node</td>
<td>8006</td>
<td>JSON-RPC</td>
<td>Transaction processing, consensus</td>
</tr>
<tr>
<td>Miner Daemon</td>
<td>8010</td>
<td>HTTP/REST</td>
<td>Job execution, GPU management</td>
</tr>
<tr>
<td>Ollama Server</td>
<td>11434</td>
<td>HTTP/REST</td>
<td>AI model inference</td>
</tr>
</tbody>
</table>
</section>
<!-- Message Flow Timeline -->
<section class="content-section">
<h2>Message Flow Timeline</h2>
<div class="timeline">0s: User submits CLI command
└─> 0.1s: Python client called
└─> 0.2s: HTTP POST to Coordinator (port 8000)
└─> 0.3s: Coordinator validates and creates job
└─> 0.4s: RPC to Blockchain (port 8006)
└─> 0.5s: Transaction in mempool
└─> 1.0s: Job queued for miner
└─> 2.0s: Miner assigned (port 8010)
└─> 2.1s: Miner accepts job
└─> 2.2s: Ollama request (port 11434)
└─> 14.7s: Inference complete (12.5s processing)
└─> 14.8s: Result to Coordinator
└─> 15.0s: Receipt generated
└─> 15.1s: Receipt on Blockchain
└─> 17.0s: Client polls and gets result</div>
</section>
<!-- Error Handling Paths -->
<section class="content-section">
<h2>Error Handling Paths</h2>
<div class="error-box">
<h4>1. Invalid Prompt</h4>
<ul>
<li>Coordinator returns 400 error</li>
<li>CLI displays error message</li>
</ul>
</div>
<div class="error-box">
<h4>2. Miner Unavailable</h4>
<ul>
<li>Job stays in queue</li>
<li>Timeout after 60 seconds</li>
<li>Job marked as failed</li>
</ul>
</div>
<div class="error-box">
<h4>3. Ollama Error</h4>
<ul>
<li>Miner reports failure to Coordinator</li>
<li>Job marked as failed</li>
<li>No payment deducted</li>
</ul>
</div>
<div class="error-box">
<h4>4. Network Issues</h4>
<ul>
<li>Client retries with exponential backoff</li>
<li>Maximum 3 retries before giving up</li>
</ul>
</div>
</section>
<!-- Security Considerations -->
<section class="content-section">
<h2>Security Considerations</h2>
<ul>
<li><strong>API Keys</strong>: Each request authenticated with X-Api-Key header</li>
<li><strong>Proof of Work</strong>: Miner provides cryptographic proof of computation</li>
<li><strong>Payment Escrow</strong>: Tokens held in smart contract until completion</li>
<li><strong>Rate Limiting</strong>: Coordinator limits requests per client</li>
</ul>
</section>
<!-- Additional Resources -->
<section class="content-section">
<h2>Related Documentation</h2>
<ul>
<li><a href="coordinator-api.html">Coordinator API Documentation</a> - Detailed API reference for the coordinator service</li>
<li><a href="blockchain-node.html">Blockchain Node Documentation</a> - Learn about the blockchain node and RPC API</li>
<li><a href="miners.html">Miner Documentation</a> - Guide to setting up and running a miner</li>
<li><a href="clients.html">Client Documentation</a> - Using the CLI and Python client</li>
<li><a href="components.html">System Components</a> - Overview of all AITBC components</li>
<li><a href="full-documentation.html">Full Documentation</a> - Complete technical documentation</li>
</ul>
</section>
<!-- Monitoring Points -->
<section class="content-section">
<h2>Monitoring Points</h2>
<ul>
<li>Coordinator logs all API calls to <span class="inline-code">/var/log/aitbc/coordinator.log</span></li>
<li>Miner logs GPU utilization to <span class="inline-code">/var/log/aitbc/miner.log</span></li>
<li>Blockchain logs all transactions to <span class="inline-code">/var/log/aitbc/node.log</span></li>
<li>Prometheus metrics available at <span class="inline-code">http://localhost:9090/metrics</span></li>
</ul>
</section>
</div>
</main>
<footer>
<div class="container">
<p>&copy; 2026 AITBC. All rights reserved.</p>
</div>
</footer>
<script src="js/theme.js"></script>
<script src="/assets/js/global-header.js"></script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink