oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 7 Packages Projects Releases Wiki Activity
Files
06e48ef34ba1e9f26a73fab280b7dca28aed411c
aitbc/docs/1_project/1_files.md
oib 06e48ef34b chore: standardize configuration, logging, and error handling across blockchain node and coordinator API 
- Add infrastructure.md and workflow files to .gitignore to prevent sensitive info leaks
- Change blockchain node mempool backend default from memory to database for persistence
- Refactor blockchain node logger with StructuredLogFormatter and AuditLogger (consistent with coordinator)
- Add structured logging fields: service, module, function, line number
- Unify coordinator config with Database
2026-02-13 22:39:43 +01:00

21 KiB
Raw Blame History

AITBC Repository File Audit

This document categorizes all files and folders in the repository by their status:

  • Whitelist (✅): Active, up-to-date, essential
  • Greylist (⚠️): Uncertain status, may need review
  • Blacklist (❌): Legacy, unused, outdated, candidates for removal

Last updated: 2026-02-12 (evening)

Whitelist ✅ (Active & Essential)

Core Applications (apps/)

Path Status Notes
apps/coordinator-api/ ✅ Active Main API service, recently updated (Feb 2026)
apps/explorer-web/ ✅ Active Blockchain explorer, recently updated
apps/wallet-daemon/ ✅ Active Wallet service, deployed in production
apps/trade-exchange/ ✅ Active Bitcoin exchange, deployed
apps/zk-circuits/ ✅ Active ZK proof circuits, 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/cli/test_cli_integration.py ✅ Active 24 CLI → live coordinator integration tests (Feb 2026)

Scripts (scripts/)

Path Status Notes
scripts/aitbc-cli.sh ✅ Active Main CLI tool, heavily used
scripts/gpu/gpu_miner_host.py ✅ Active Production GPU miner
scripts/gpu/gpu_miner_host_wrapper.sh ✅ Active Systemd wrapper
scripts/deploy/ ✅ Active Deployment scripts
scripts/service/ ✅ Active Service management
scripts/dev_services.sh ✅ Active Local development
scripts/testing/ ✅ Active Test scripts (moved from root, 13 files)

Infrastructure (infra/, systemd/)

Path Status Notes
infra/nginx/ ✅ Active Production nginx configs
systemd/aitbc-host-gpu-miner.service ✅ Active Production service
systemd/coordinator-api.service ✅ Active Production service

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/done.md ✅ Active Completion tracking
docs/roadmap.md ✅ Active Development roadmap
docs/developer/testing/localhost-testing-scenario.md ✅ Active Testing guide
docs/reference/components/miner_node.md ✅ Active Miner documentation
docs/reference/components/coordinator_api.md ✅ Active API documentation
docs/developer/integration/skills-framework.md ✅ Active Skills documentation
docs/guides/ ✅ Active Development guides (moved from root)
docs/guides/block-production-runbook.md ✅ Active Block production operational runbook
docs/guides/blockchain-node-deployment.md ✅ Active Blockchain node deployment guide
docs/reports/ ✅ Active Generated reports (moved from root)
docs/reference/specs/receipt-spec.md ✅ Active Receipt spec v1.1 (multi-sig, ZK, Merkle)

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.10/3.11/3.12)

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-utils/)

Path Status Notes
dev-utils/ ✅ Active Development utilities (newly created)
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 new structure
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 ⚠️ Duplicate Recreated in root (exists in scripts/testing/)

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/)

Path Status Notes
contracts/ZKReceiptVerifier.sol ✅ Active ZK receipt verifier contract
contracts/Groth16Verifier.sol ✅ Active Groth16 verifier stub (snarkjs-replaceable)
contracts/scripts/security-analysis.sh ✅ Active Slither + Mythril analysis script
contracts/scripts/deploy-testnet.sh ✅ Active Testnet deployment script

Greylist ⚠️ (Needs Review)

Packages

Path Status Notes
packages/solidity/aitbc-token/ 📋 Planned Smart contracts, deployment planned - see roadmap Stage 20

Scripts

Path Status Notes
scripts/test/ ✅ Keep 7 test scripts, all current (Jan 2026)

Documentation

Path Status Notes
docs/developer/ ✅ Keep 6 markdown files
docs/operator/ ✅ Keep 5 markdown files
docs/user/ ✅ Keep 1 markdown file
docs/tutorials/ ✅ Keep 3 markdown files

Infrastructure

Path Status Notes
infra/k8s/ ✅ Keep 5 yaml files (backup, cert-manager, netpol, sealed-secrets)

Extensions

Path Status Notes
extensions/aitbc-wallet-firefox/ ✅ Keep Firefox extension source (7 files)
extensions/aitbc-wallet-firefox-v1.0.5.xpi ✅ Keep Built extension package

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/ 📋 Placeholder Stage 5 - Documentation
docs/developer/tutorials/ 📋 Placeholder Stage 5 - Documentation
docs/reference/specs/ 📋 Placeholder Stage 5 - Documentation
infra/terraform/environments/staging/ 📋 Placeholder Stage 5 - Infrastructure
infra/terraform/environments/prod/ 📋 Placeholder Stage 5 - Infrastructure
infra/helm/values/dev/ 📋 Placeholder Stage 5 - Infrastructure
infra/helm/values/staging/ 📋 Placeholder Stage 5 - Infrastructure
infra/helm/values/prod/ 📋 Placeholder Stage 5 - Infrastructure
apps/coordinator-api/migrations/ 📋 Placeholder Alembic migrations
apps/pool-hub/src/app/routers/ 📋 Placeholder Stage 3 - Pool Hub
apps/pool-hub/src/app/registry/ 📋 Placeholder Stage 3 - Pool Hub
apps/pool-hub/src/app/scoring/ 📋 Placeholder Stage 3 - Pool Hub

Blacklist ❌ (Abandoned - Remove)

Abandoned Empty Folders (Created but never used)

Path Status Notes
apps/client-web/src/ ❌ Remove Created Sep 2025, never implemented
apps/client-web/public/ ❌ Remove Created Sep 2025, never implemented
apps/marketplace-ui/ ❌ Remove Superseded by marketplace-web
apps/wallet-cli/ ❌ Remove Superseded by cli/wallet.py
packages/py/aitbc-core/src/ ❌ Remove Created Sep 2025, never implemented
packages/py/aitbc-p2p/src/ ❌ Remove Created Sep 2025, never implemented
packages/py/aitbc-scheduler/src/ ❌ Remove Created Sep 2025, never implemented
packages/js/ui-widgets/src/ ❌ Remove Created Sep 2025, never implemented
protocols/api/ ❌ Remove Never implemented
protocols/payouts/ ❌ Remove Never implemented
data/fixtures/ ❌ Remove Never populated
data/samples/ ❌ Remove Never populated
tools/mkdiagram/ ❌ Remove Never implemented
examples/quickstart-client-python/ ❌ Remove Never implemented
examples/quickstart-client-js/node/ ❌ Remove Never implemented
examples/quickstart-client-js/browser/ ❌ Remove Never implemented
examples/receipts-sign-verify/python/ ❌ Remove Never implemented
examples/receipts-sign-verify/js/ ❌ Remove Never implemented
scripts/env/ ❌ Remove Never populated
windsurf/prompts/ ❌ Remove Superseded by .windsurf/
windsurf/tasks/ ❌ Remove Superseded by .windsurf/

Duplicate/Redundant Folders

Path Status Notes
python-sdk/ ❌ Duplicate Duplicates packages/py/aitbc-sdk/
windsurf/ ❌ Duplicate Superseded by .windsurf/
configs/ ❌ Duplicate Empty subfolders, duplicates infra/ and systemd/
docs/user-guide/ ❌ Duplicate Duplicates docs/user/

Ecosystem Folders (Scaffolded but Unused)

Path Status Notes
ecosystem/ ❌ Unused Only has empty academic/ subfolder
ecosystem-analytics/ ❌ Unused Scaffolded Dec 2025, never used
ecosystem-certification/ ❌ Unused Scaffolded Dec 2025, never used
ecosystem-extensions/ ❌ Unused Only has template folder
enterprise-connectors/ ❌ Unused Scaffolded Dec 2025, never used

Research Folders (Scaffolded but Unused)

Path Status Notes
research/autonomous-agents/ ❌ Unused Scaffolded, no active work
research/consortium/ ❌ Unused Scaffolded, no active work
research/prototypes/ ❌ Unused Scaffolded, no active work
research/standards/ ❌ Unused Scaffolded, no active work

Generated/Build Artifacts (Should be in .gitignore)

Path Status Notes
packages/solidity/aitbc-token/typechain-types/ ❌ Generated Build artifact
apps/explorer-web/dist/ ❌ Generated Build artifact
logs/ ❌ Generated Runtime logs

Issues Found (2026-02-11)

Empty Directories (Delete)

Path Action
apps/blockchain-node/src/aitbc_chain/ledger/ Delete — empty placeholder, never implemented
apps/blockchain-node/src/aitbc_chain/mempool/ Delete — empty dir, mempool logic is in mempool.py
apps/coordinator-api/src/app/ws/ Delete — empty WebSocket placeholder, never implemented
apps/explorer-web/public/js/components/ Delete — empty, TS components are in src/components/
apps/explorer-web/public/js/pages/ Delete — empty, TS pages are in src/pages/
apps/explorer-web/public/js/vendors/ Delete — empty vendor dir
apps/explorer-web/public/assets/ Delete — empty assets dir
packages/py/aitbc-crypto/build/bdist.linux-x86_64/ Delete — build artifact

Files in Wrong Location (Move)

Current Path Correct Path Reason
apps/coordinator-api/coordinator.db gitignored / data/ SQLite database should not be in git
apps/coordinator-api/.env gitignored Environment file with secrets, should not be in git
apps/.service_pids gitignored Runtime PID file, should not be in git
src/aitbc_chain/ apps/blockchain-node/src/aitbc_chain/ Duplicate/stale copy of blockchain node source
website/docs-clients.html website/docs/docs-clients.html Inconsistent location, duplicate of file in docs/
website/docs-developers.html website/docs/docs-developers.html Inconsistent location, duplicate of file in docs/
website/docs-miners.html website/docs/docs-miners.html Inconsistent location, duplicate of file in docs/
website/docs-index.html website/docs/index.html Inconsistent location, duplicate of file in docs/

Legacy Files (Delete)

Path Reason
SECURITY_CLEANUP_GUIDE.md One-time cleanup guide, already completed
apps/trade-exchange/index_working.html Backup copy of index.html
apps/trade-exchange/index.prod.html Superseded by build.py production build
apps/trade-exchange/index.real.html Superseded by build.py production build
tests/conftest_fixtures.py Unused alternate conftest
tests/conftest_full.py Unused alternate conftest
tests/conftest_path.py Unused alternate conftest
tests/pytest_simple.ini Duplicate of root pytest.ini
tests/test_blockchain_simple.py Superseded by test_blockchain_nodes.py
tests/test_blockchain_final.py Superseded by test_blockchain_nodes.py
tests/test_discovery.py One-time discovery script
tests/test_windsurf_integration.py IDE-specific test, not for GitHub
scripts/exchange-router-fixed.py One-time fix script
scripts/start_mock_blockchain.sh Superseded by tests/mock_blockchain_node.py
apps/marketplace-web/src/counter.ts Vite template boilerplate, unused
apps/marketplace-web/src/typescript.svg Vite template boilerplate, unused
apps/marketplace-web/public/vite.svg Vite template boilerplate, unused
.vscode/ IDE-specific, should be gitignored

Debug Print Statements (Replace with logging)

File Lines Statement
apps/coordinator-api/src/app/routers/exchange.py 112 print(f"Error minting tokens: {e}")
apps/coordinator-api/src/app/routers/governance.py 352-376 4x print(f"Executing ...")
apps/coordinator-api/src/app/services/receipts.py 132 print(f"Failed to generate ZK proof: {e}")
apps/coordinator-api/src/app/services/blockchain.py 47 print(f"Error getting balance: {e}")
apps/coordinator-api/src/app/services/bitcoin_wallet.py 34-134 8x print(...) debug statements
apps/coordinator-api/src/app/storage/db_pg.py 206 print("✅ PostgreSQL database initialized successfully!")

Summary Statistics

Category Count Action
Whitelist ✅ ~60 items Keep and maintain
Greylist ⚠️ 0 items All resolved
Placeholders 📋 12 folders Fill per roadmap
Removed ❌ 35 items Cleaned up 2026-01-24
Empty dirs 8 dirs Delete
Misplaced files 8 files Move or gitignore
Legacy files 18 files Delete
Debug prints 17 statements Replace with logger

Completed Actions (2026-01-24)

  1. Cleanup Done:

    • ✅ Removed 21 abandoned/duplicate folders
    • ✅ Updated .gitignore with comprehensive rules
    • ✅ Created this audit document

  2. Additional Cleanup (2026-01-24):

    • ✅ Removed apps/miner-node/ (superseded by scripts/gpu/)
    • ✅ Removed apps/miner-dashboard/ (superseded by website/dashboards/)
    • ✅ Removed docs/bootstrap/ (empty)
    • ✅ Removed 5 GPU miner variants (kept only gpu_miner_host.py)
    • ✅ Removed 3 extension variants (kept only aitbc-wallet-firefox/)

  3. Final Cleanup (2026-01-24):

    • ✅ Removed api/ folder (mock no longer needed - using live production)
    • ✅ Removed governance/ folder (too far in future)
    • ✅ Removed protocols/ folder (spec moved to docs/reference/specs/)
    • ✅ Moved protocols/receipts/spec.md → docs/reference/specs/receipt-spec.md
    • ✅ Added ZKReceiptVerifier and receipt spec to roadmap Stage 20

  4. Placeholder Plan (see roadmap.md Stage 19):

    • Q1 2026: Documentation folders (docs/user/guides/, docs/developer/tutorials/, docs/reference/specs/)
    • Q2 2026: Infrastructure (infra/terraform/, infra/helm/)
    • Q2 2026: Pool Hub components

  5. Directory Organization (2026-01-29):

    • ✅ Created docs/guides/ and moved 2 guide files from root
    • ✅ Created docs/reports/ and moved 10 report files from root
    • ✅ Created scripts/testing/ and moved 13 test scripts from root
    • ✅ Created dev-utils/ and moved aitbc-pythonpath.pth
    • ✅ Moved coordinator.db to data/ directory
    • ✅ Updated README.md with new structure
    • ✅ Created index README files for new directories

Folder Structure Recommendation

aitbc/
├── apps/                    # Core applications
│   ├── coordinator-api/     # ✅ Keep
│   ├── explorer-web/        # ✅ Keep
│   ├── marketplace-web/     # ✅ Keep
│   ├── wallet-daemon/       # ✅ Keep
│   └── zk-circuits/         # ✅ Keep
├── cli/                     # ✅ CLI tools
├── docs/                    # ✅ Markdown documentation
│   ├── guides/              # Development guides
│   └── reports/             # Generated reports
├── infra/                   # ✅ Infrastructure configs
├── packages/                # ✅ Keep (aitbc-crypto, aitbc-sdk, aitbc-token)
├── plugins/                 # ✅ Keep (ollama)
├── scripts/                 # ✅ Keep - organized
│   └── testing/             # Test scripts
├── systemd/                 # ✅ Keep
├── tests/                   # ✅ Keep (e2e, integration, unit, security, load)
├── website/                 # ✅ Keep
├── dev-utils/               # ✅ Development utilities
├── data/                    # ✅ Runtime data (gitignored)
└── .windsurf/               # ✅ Keep

Folders Removed (2026-01-24):

  • ✅ ecosystem*/ (all 4 folders) - removed
  • ✅ enterprise-connectors/ - removed
  • ✅ research/ - removed
  • ✅ python-sdk/ - removed (duplicate)
  • ✅ windsurf/ - removed (duplicate of .windsurf/)
  • ✅ configs/ - removed (duplicated infra/)
  • ✅ Empty apps/ subfolders - removed (client-web, marketplace-ui, wallet-cli)
  • ✅ Empty packages/ subfolders - removed (aitbc-core, aitbc-p2p, aitbc-scheduler, ui-widgets)
  • ✅ Empty examples/ subfolders - removed
  • ✅ tools/ - removed (empty)
  • ✅ docs/user-guide/ - removed (duplicate)