oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 7 Packages Projects Releases Wiki Activity
Files
d7590c5852763f1003d07b306c8c6674fed54d66
aitbc/docs/beginner/02_project/1_files.md

400 lines
23 KiB
Markdown
Raw Blame History

# AITBC Repository File Structure
This document describes the current organization and status of files and folders in the repository.
Last updated: 2026-03-25
---
## Whitelist ✅ (Active & Essential)
### Core Applications (`apps/`)
| Path | Status | Notes |
|------|--------|-------|
| `apps/coordinator-api/` | ✅ Active | Main API service, standardized (Mar 2026) |
| `apps/blockchain-explorer/` | ✅ Active | Agent-first blockchain explorer, recently optimized (Mar 2026) |
| `apps/blockchain-node/` | ✅ Active | Blockchain node, standardized (Mar 2026) |
| `apps/trade-exchange/` | ✅ Active | Bitcoin exchange, deployed |
| `apps/marketplace-web/` | ✅ Active | Marketplace frontend, deployed |
| `apps/coordinator-api/src/app/domain/gpu_marketplace.py` | ✅ Active | GPURegistry, GPUBooking, GPUReview SQLModel tables (Feb 2026) |
| `apps/coordinator-api/tests/test_gpu_marketplace.py` | ✅ Active | 22 GPU marketplace tests (Feb 2026) |
| `apps/coordinator-api/tests/test_billing.py` | ✅ Active | 21 billing/usage-tracking tests (Feb 2026) |
| `apps/coordinator-api/tests/conftest.py` | ✅ Active | App namespace isolation for coordinator tests |
| `tests/` | ✅ Active | Test suites (reorganized Mar 2026) |
| `tests/cli/` | ✅ Active | CLI tests (28 files, organized Mar 2026) |
| `tests/integration/` | ✅ Active | Integration tests (28 files, organized Mar 2026) |
| `tests/security/` | ✅ Active | Security tests (5 files, organized Mar 2026) |
| `tests/explorer/` | ✅ Active | Explorer tests (2 files, organized Mar 2026) |
| `tests/websocket/` | ✅ Active | WebSocket tests (2 files, organized Mar 2026) |
| `tests/testing/` | ✅ Active | Performance/testing utilities (25 files, organized Mar 2026) |
| `tests/unit/` | ✅ Active | Unit tests (9 files, organized Mar 2026) |
| `tests/e2e/` | ✅ Active | End-to-end tests (26 files, organized Mar 2026) |
| `tests/docs/` | ✅ Active | Test documentation (5 files, organized Mar 2026) |
| `tests/conftest.py` | ✅ Active | Test configuration (root level) |
| `tests/test_runner.py` | ✅ Active | Test runner (root level) |
### Scripts (`scripts/`)
| Path | Status | Notes |
|------|--------|-------|
| `scripts/aitbc-cli.sh` | ✅ Active | Main CLI tool, heavily used |
| `scripts/dev/gpu/gpu_miner_host.py` | ✅ Active | Production GPU miner, standardized (Mar 2026) |
| `scripts/services/` | ✅ Active | Service files (5 FastAPI services, moved Mar 2026) |
| `scripts/deployment/` | ✅ Active | Deployment scripts (35 files, organized Mar 2026) |
| `scripts/testing/` | ✅ Active | Test scripts (20 files, organized Mar 2026) |
| `scripts/monitoring/` | ✅ Active | Monitoring scripts (3 files, organized Mar 2026) |
| `scripts/development/` | ✅ Active | Development scripts (6 files, organized Mar 2026) |
| `scripts/utils/` | ✅ Active | Utility scripts (40 files, organized Mar 2026) |
| `scripts/manage-services.sh` | ✅ Active | Main service management script (updated Mar 2026) |
| `scripts/README.md` | ✅ Active | Scripts documentation |
| `scripts/deploy/` | ✅ Active | Legacy deployment scripts (27 files) |
| `scripts/gpu/` | ✅ Active | GPU service scripts (9 files, moved to services/) |
### Infrastructure (`infra/`, `systemd/`)
| Path | Status | Notes |
|------|--------|-------|
| `infra/nginx/` | ✅ Active | Production nginx configs |
| `systemd/` | ✅ Active | All 19+ standardized service files (Mar 2026) |
| `systemd/aitbc-gpu-miner.service` | ✅ Active | Standardized GPU miner service |
| `systemd/aitbc-multimodal-gpu.service` | ✅ Active | Renamed GPU multimodal service (Mar 2026) |
| `systemd/aitbc-blockchain-node.service` | ✅ Active | Standardized blockchain node |
| `systemd/aitbc-blockchain-rpc.service` | ✅ Active | Standardized RPC service |
| `systemd/aitbc-coordinator-api.service` | ✅ Active | Standardized coordinator API |
| `systemd/aitbc-wallet.service` | ✅ Active | Fixed and standardized (Mar 2026) |
| `systemd/aitbc-loadbalancer-geo.service` | ✅ Active | Fixed and standardized (Mar 2026) |
| `systemd/aitbc-marketplace-enhanced.service` | ✅ Active | Fixed and standardized (Mar 2026) |
### Website (`website/`)
| Path | Status | Notes |
|------|--------|-------|
| `website/docs/` | ✅ Active | HTML documentation, recently refactored |
| `website/docs/css/docs.css` | ✅ Active | Shared CSS (1232 lines) |
| `website/docs/js/theme.js` | ✅ Active | Theme toggle |
| `website/index.html` | ✅ Active | Main website |
| `website/dashboards/` | ✅ Active | Admin/miner dashboards |
### Documentation (`docs/`)
| Path | Status | Notes |
|------|--------|-------|
| `docs/1_project/` | ✅ Active | Project management docs (updated Mar 2026) |
| `docs/1_project/aitbc.md` | ✅ Active | Secondary server deployment guide (updated Mar 2026) |
| `docs/1_project/aitbc1.md` | ✅ Active | Primary server deployment guide (updated Mar 2026) |
| `docs/1_project/3_infrastructure.md` | ✅ Active | Infrastructure documentation (updated Mar 2026) |
| `docs/infrastructure/` | ✅ Active | Infrastructure documentation (Mar 2026) |
| `docs/infrastructure/codebase-update-summary.md` | ✅ Active | Comprehensive standardization summary (Mar 2026) |
| `docs/DOCS_WORKFLOW_COMPLETION_SUMMARY.md` | ✅ Active | Documentation updates completion (Mar 2026) |
| `docs/0_getting_started/` | ✅ Active | Getting started guides |
| `docs/2_clients/` | ✅ Active | Client documentation |
| `docs/3_miners/` | ✅ Active | Miner documentation |
| `docs/4_blockchain/` | ✅ Active | Blockchain documentation |
| `docs/5_reference/` | ✅ Active | Reference materials |
| `docs/6_architecture/` | ✅ Active | Architecture documentation |
| `docs/7_deployment/` | ✅ Active | Deployment guides |
| `docs/8_development/` | ✅ Active | Development documentation |
| `docs/9_security/` | ✅ Active | Security documentation |
| `docs/10_plan/` | ✅ Active | Planning documentation, updated (Mar 2026) |
| `docs/10_plan/99_currentissue.md` | ✅ Active | Current issues with standardization completion (Mar 2026) |
| `.windsurf/workflows/` | ✅ Active | Development workflows (Mar 2026) |
| `.windsurf/workflows/aitbc-services-monitoring.md` | ✅ Active | Services monitoring workflow (Mar 2026) |
### CLI Tools (`cli/`)
| Path | Status | Notes |
|------|--------|-------|
| `cli/aitbc_cli/commands/client.py` | ✅ Active | Client CLI (submit, batch-submit, templates, history) |
| `cli/aitbc_cli/commands/miner.py` | ✅ Active | Miner CLI (register, earnings, capabilities, concurrent) |
| `cli/aitbc_cli/commands/wallet.py` | ✅ Active | Wallet CLI (balance, staking, multisig, backup/restore) |
| `cli/aitbc_cli/commands/auth.py` | ✅ Active | Auth CLI (login, tokens, API keys) |
| `cli/aitbc_cli/commands/blockchain.py` | ✅ Active | Blockchain queries |
| `cli/aitbc_cli/commands/marketplace.py` | ✅ Active | GPU marketplace operations |
| `cli/aitbc_cli/commands/admin.py` | ✅ Active | System administration, audit logging |
| `cli/aitbc_cli/commands/config.py` | ✅ Active | Configuration, profiles, encrypted secrets |
| `cli/aitbc_cli/commands/monitor.py` | ✅ Active | Dashboard, metrics, alerts, webhooks |
| `cli/aitbc_cli/commands/simulate.py` | ✅ Active | Test simulation framework |
| `cli/aitbc_cli/plugins.py` | ✅ Active | Plugin system for custom commands |
| `cli/aitbc_cli/main.py` | ✅ Active | CLI entry point (12 command groups) |
| `cli/man/aitbc.1` | ✅ Active | Man page |
| `cli/aitbc_shell_completion.sh` | ✅ Active | Shell completion script |
| `cli/test_ollama_gpu_provider.py` | ✅ Active | GPU testing |
| `.github/workflows/cli-tests.yml` | ✅ Active | CI/CD for CLI tests (Python 3.11/3.12/3.13) |
### Home Scripts (`home/`)
| Path | Status | Notes |
|------|--------|-------|
| `home/client/` | ✅ Active | Client test scripts |
| `home/miner/` | ✅ Active | Miner test scripts |
| `home/quick_job.py` | ✅ Active | Quick job submission |
| `home/simple_job_flow.py` | ✅ Active | Job flow testing |
### Plugins (`plugins/`)
| Path | Status | Notes |
|------|--------|-------|
| `plugins/ollama/` | ✅ Active | Ollama integration |
### Development Utilities (`dev/`)
| Path | Status | Notes |
|------|--------|-------|
| `dev/` | ✅ Active | Development environment (reorganized, Mar 2026) |
| `dev/cli/` | ✅ Active | CLI development environment (moved from cli-dev, Mar 2026) |
| `dev/scripts/` | ✅ Active | Development scripts (79 Python files) |
| `dev/cache/` | ✅ Active | Development cache files |
| `dev/env/` | ✅ Active | Environment configurations |
| `dev/multi-chain/` | ✅ Active | Multi-chain development files |
| `dev/tests/` | ✅ Active | Development test files |
### Development Utilities (`dev-utils/`)
| Path | Status | Notes |
|------|--------|-------|
| `dev-utils/` | ✅ Active | Development utilities (legacy) |
| `dev-utils/aitbc-pythonpath.pth` | ✅ Active | Python path configuration |
### Data Directory (`data/`)
| Path | Status | Notes |
|------|--------|-------|
| `data/` | ✅ Active | Runtime data directory (gitignored) |
| `data/coordinator.db` | ⚠️ Runtime | SQLite database, moved from root |
### Root Files
| Path | Status | Notes |
|------|--------|-------|
| `README.md` | ✅ Active | Project readme, updated with standardization badges (Mar 2026) |
| `LICENSE` | ✅ Active | License file |
| `.gitignore` | ✅ Active | Recently updated (145 lines) |
| `pyproject.toml` | ✅ Active | Python project config |
| `.editorconfig` | ✅ Active | Editor config |
| `pytest.ini` | ✅ Active | Pytest configuration with custom markers |
| `CLEANUP_SUMMARY.md` | ✅ Active | Documentation of directory cleanup |
| `test_block_import.py` | ✅ Resolved | Moved to `tests/verification/test_block_import.py` |
### Backup Directory (`backup/`)
| Path | Status | Notes |
|------|--------|-------|
| `backup/` | ✅ Active | Backup archive storage (organized, Mar 2026) |
| `backup/explorer_backup_20260306_162316.tar.gz` | ✅ Active | Explorer TypeScript source backup (15.2 MB) |
| `backup/BACKUP_INDEX.md` | ✅ Active | Backup inventory and restoration instructions |
---
### Blockchain Node (`apps/blockchain-node/`)
| Path | Status | Notes |
|------|--------|-------|
| `apps/blockchain-node/` | ✅ Active | Blockchain node with PoA, mempool, sync (Stage 20/21/22 complete) |
| `apps/blockchain-node/src/aitbc_chain/mempool.py` | ✅ Active | Dual-backend mempool (memory + SQLite) |
| `apps/blockchain-node/src/aitbc_chain/sync.py` | ✅ Active | Chain sync with conflict resolution |
| `apps/blockchain-node/src/aitbc_chain/consensus/poa.py` | ✅ Active | PoA proposer with circuit breaker |
| `apps/blockchain-node/src/aitbc_chain/app.py` | ✅ Active | FastAPI app with rate limiting middleware |
| `apps/blockchain-node/tests/test_mempool.py` | ✅ Active | 27 mempool tests |
| `apps/blockchain-node/tests/test_sync.py` | ✅ Active | 23 sync tests |
### Smart Contracts (`contracts/`) 📜 **EXPANDED**
| Path | Status | Notes |
|------|--------|-------|
| `contracts/contracts/AIPowerRental.sol` | ✅ Active | Handles decentralized GPU/AI compute rentals |
| `contracts/contracts/AITBCPaymentProcessor.sol` | ✅ Active | AITBC token flow and automated settlements |
| `contracts/contracts/DisputeResolution.sol` | ✅ Active | Arbitration for OpenClaw marketplace disputes |
| `contracts/contracts/EscrowService.sol` | ✅ Active | Multi-signature execution escrow locks |
| `contracts/contracts/DynamicPricing.sol` | ✅ Active | Supply/Demand algorithmic pricing |
| `contracts/contracts/PerformanceVerifier.sol` | ✅ Active | On-chain ZK verification of AI inference quality |
| `contracts/contracts/AgentStaking.sol` | ✅ Active | Agent ecosystem reputation staking |
| `contracts/contracts/AgentBounty.sol` | ✅ Active | Crowdsourced task resolution logic |
| `contracts/contracts/ZKReceiptVerifier.sol` | ✅ Active | ZK receipt verifier contract |
| `contracts/contracts/BountyIntegration.sol` | ✅ Active | Cross-contract event handling |
| `contracts/AgentWallet.sol` | ✅ Active | Isolated agent-specific wallets |
| `contracts/AgentMemory.sol` | ✅ Active | IPFS CID anchoring for agent memory |
| `contracts/KnowledgeGraphMarket.sol` | ✅ Active | Shared knowledge graph marketplace |
| `contracts/MemoryVerifier.sol` | ✅ Active | ZK-proof verification for data retrieval |
| `contracts/CrossChainReputation.sol` | ✅ Active | Portable reputation scores |
| `contracts/AgentCommunication.sol` | ✅ Active | Secure agent messaging |
| `contracts/scripts/` | ✅ Active | Hardhat deployment & verification scripts |
---
## Future Placeholders 📋 (Keep - Will Be Populated)
These empty folders are intentional scaffolding for planned future work per the roadmap.
| Path | Status | Roadmap Stage |
|------|--------|---------------|
| `docs/user/guides/` | ✅ Complete | Stage 19 - Documentation (Q1 2026) |
| `docs/developer/tutorials/` | ✅ Complete | Stage 19 - Documentation (Q1 2026) |
| `docs/reference/specs/` | ✅ Complete | Stage 19 - Documentation (Q1 2026) |
| `infra/terraform/environments/staging/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
| `infra/terraform/environments/prod/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
| `infra/helm/values/dev/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
| `infra/helm/values/staging/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
| `infra/helm/values/prod/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
| `apps/coordinator-api/migrations/` | ✅ Complete | Stage 19 - Application Components (Q1 2026) |
| `apps/pool-hub/src/app/routers/` | ✅ Complete | Stage 19 - Application Components (Q1 2026) |
| `apps/pool-hub/src/app/registry/` | ✅ Complete | Stage 19 - Application Components (Q1 2026) |
| `apps/pool-hub/src/app/scoring/` | ✅ Complete | Stage 19 - Application Components (Q1 2026) |
---
## Summary Statistics
| Category | Count | Status |
|----------|-------|--------|
| **Whitelist ✅** | ~85 items | Active and maintained (Mar 2026) |
| **Placeholders 📋** | 12 folders | All complete (Stage 19) |
| **Standardized Services** | 19+ services | 100% standardized (Mar 2026) |
| **Development Scripts** | 79 files | Organized in dev/scripts/ (Mar 2026) |
| **Deployment Scripts** | 35 files | Organized in scripts/deploy/ (Mar 2026) |
| **Documentation Files** | 200+ files | Updated and current (Mar 2026) |
| **Backup Archives** | 1+ files | Organized in backup/ (Mar 2026) |
| **Debug prints** | 17 statements | Replace with logger |
## Recent Major Updates (March 2026)
### ✅ Complete Infrastructure Standardization
- **19+ services** standardized to use `aitbc` user and `/opt/aitbc` paths
- **Duplicate services** removed and cleaned up
- **Service naming** conventions improved (e.g., GPU multimodal renamed)
- **All services** operational with 100% health score
- **Automated verification** tools implemented
### ✅ Enhanced Documentation
- **Infrastructure documentation** created and updated
- **Service monitoring workflow** implemented
- **Codebase verification script** developed
- **Project files documentation** updated to reflect current state
### ✅ Improved Organization
- **Development environment** reorganized into `dev/` structure
- **Scripts organized** by purpose (deploy, dev, testing)
- **Workflows documented** for repeatable processes
- **File organization prevention** system implemented
### ✅ Complete Scripts and Tests Organization (March 25, 2026)
- **Scripts organized** by purpose into 6 categories (services, deployment, testing, monitoring, development, utils)
- **Test files organized** by function into 9 categories (cli, integration, security, explorer, websocket, testing, unit, e2e, docs)
- **Service scripts** moved to dedicated `scripts/services/` folder
- **Documentation updated** to reflect new file locations
- **No codebase rewrites** needed - all paths already properly configured
### ✅ Server Architecture Updates (March 25, 2026)
- **aitbc1** established as primary server (https://aitbc1.bubuit.net) with reverse proxy role
- **aitbc** established as secondary server (https://aitbc.bubuit.net) with application services
- **SSH access** simplified to `ssh aitbc` and `ssh aitbc1` (root login, no sudo needed)
- **Deployment guides** updated to reflect new primary/secondary architecture
- **Infrastructure documentation** updated for two-server setup
### ✅ Documentation Standardization (March 25, 2026)
- **All sudo references** removed from systemctl commands (root access)
- **SSH references** updated to use new server names
- **Service paths** updated in documentation to reflect new organization
- **12 documentation files** updated across the codebase
- **Consistent command patterns** applied throughout
### ✅ Explorer Architecture Simplification (March 6, 2026)
- **TypeScript explorer** merged into Python blockchain-explorer
- **Agent-first architecture** strengthened with single service
- **Source code deleted** with proper backup (15.2 MB archive)
- **Documentation updated** across all reference files
---
## Folder Structure Recommendation
```
aitbc/
├── apps/ # Core applications
│ ├── coordinator-api/ # ✅ Keep - Standardized (Mar 2026)
│ ├── explorer-web/ # ✅ Keep
│ ├── marketplace-web/ # ✅ Keep
│ ├── trade-exchange/ # ✅ Keep
│ ├── blockchain-node/ # ✅ Keep - Standardized (Mar 2026)
│ ├── blockchain-explorer/ # ✅ Keep - Standardized (Mar 2026)
│ └── zk-circuits/ # ✅ Keep
├── cli/ # ✅ CLI tools
├── contracts/ # ✅ Smart contracts
├── dev/ # ✅ Development environment (Mar 2026)
│ ├── cli/ # ✅ CLI development environment (moved Mar 2026)
│ ├── scripts/ # Development scripts (79 files)
│ ├── cache/ # Development cache
│ ├── env/ # Environment configs
│ ├── multi-chain/ # Multi-chain files
│ └── tests/ # Development tests
├── backup/ # ✅ Backup archive storage (Mar 2026)
│ ├── explorer_backup_*.tar.gz # Application backups
│ └── BACKUP_INDEX.md # Backup inventory
├── docs/ # ✅ Numbered documentation structure
│ ├── infrastructure/ # ✅ Infrastructure docs (Mar 2026)
│ ├── 0_getting_started/ # Getting started guides
│ ├── 1_project/ # Project management
│ ├── 2_clients/ # Client documentation
│ ├── 3_miners/ # Miner documentation
│ ├── 4_blockchain/ # Blockchain documentation
│ ├── 5_reference/ # Reference materials
│ ├── 6_architecture/ # Architecture documentation
│ ├── 7_deployment/ # Deployment guides
│ ├── 8_development/ # Development documentation
│ ├── 9_security/ # Security documentation
│ └── 10_plan/ # Planning documentation
├── extensions/ # ✅ Browser extensions (Firefox wallet)
├── infra/ # ✅ Infrastructure configs
│ ├── k8s/ # Kubernetes manifests
│ └── nginx/ # Nginx configurations
├── packages/ # ✅ Shared libraries
│ ├── py/aitbc-crypto/ # Cryptographic primitives
│ ├── py/aitbc-sdk/ # Python SDK
│ └── solidity/aitbc-token/# ERC-20 token contract
├── plugins/ # ✅ Keep (ollama)
├── scripts/ # ✅ Scripts organized by purpose (Mar 2026)
│ ├── services/ # ✅ Service files (5 FastAPI services)
│ ├── deployment/ # ✅ Deployment scripts (35 files)
│ ├── testing/ # ✅ Test scripts (20 files)
│ ├── monitoring/ # ✅ Monitoring scripts (3 files)
│ ├── development/ # ✅ Development scripts (6 files)
│ ├── utils/ # ✅ Utility scripts (40 files)
│ ├── deploy/ # ✅ Legacy deployment scripts (27 files)
│ ├── gpu/ # ✅ GPU service scripts (9 files)
│ ├── manage-services.sh # ✅ Main service management script
│ └── README.md # ✅ Scripts documentation
├── systemd/ # ✅ Systemd service units (19+ files)
├── tests/ # ✅ Test suites organized by function (Mar 2026)
│ ├── cli/ # ✅ CLI tests (28 files)
│ ├── integration/ # ✅ Integration tests (28 files)
│ ├── security/ # ✅ Security tests (5 files)
│ ├── explorer/ # ✅ Explorer tests (2 files)
│ ├── websocket/ # ✅ WebSocket tests (2 files)
│ ├── testing/ # ✅ Performance/testing utilities (25 files)
│ ├── unit/ # ✅ Unit tests (9 files)
│ ├── e2e/ # ✅ End-to-end tests (26 files)
│ ├── docs/ # ✅ Test documentation (5 files)
│ ├── conftest.py # ✅ Test configuration
│ └── test_runner.py # ✅ Test runner
├── website/ # ✅ Public website and HTML docs
├── dev-utils/ # ✅ Development utilities (legacy)
├── data/ # ✅ Runtime data (gitignored)
├── .windsurf/ # ✅ Keep - Workflows (Mar 2026)
└── config/ # ✅ Configuration files
```
This structure represents the current clean state of the AITBC repository with all essential components organized for optimal development and deployment workflows. The March 2026 standardization effort has resulted in:
- **100% service standardization** across all systemd services
- **Complete scripts and tests organization** by purpose and function
- **Updated server architecture** with primary/secondary server setup
- **Enhanced documentation** with comprehensive infrastructure guides
- **Automated verification tools** for maintaining standards
- **Production-ready infrastructure** with all services operational
- **Optimized CLI development** with centralized dev/cli environment
- **Agent-first architecture** with simplified explorer service
- **Comprehensive backup system** with proper git exclusion
- **Standardized SSH access** with root privileges and no sudo requirements
**Note**: Redundant `apps/logs/` directory removed - central `logs/` directory at root level is used for all logging. Redundant `assets/` directory removed - Firefox extension assets are properly organized in `extensions/aitbc-wallet-firefox/`. CLI development environment moved from `cli-dev` to `dev/cli` for better organization. Explorer TypeScript source merged into Python service and backed up.
Reference in New Issue View Git Blame Copy Permalink