chore: initialize monorepo with project scaffolding, configs, and CI setup
This commit is contained in:
oib
133
docs/bootstrap/dirs.md
Normal file
133
docs/bootstrap/dirs.md
Normal file
@ -0,0 +1,133 @@
|
||||
# AITBC Monorepo Directory Layout (Windsurf Workspace)
|
||||
|
||||
> One workspace for **all** AITBC elements (client · coordinator · miner · blockchain · pool‑hub · marketplace · wallet · docs · ops). No Docker required.
|
||||
|
||||
```
|
||||
aitbc/
|
||||
├─ .editorconfig
|
||||
├─ .gitignore
|
||||
├─ README.md # Top‑level overview, quickstart, workspace tasks
|
||||
├─ LICENSE
|
||||
├─ windsurf/ # Windsurf prompts, tasks, run configurations
|
||||
│ ├─ prompts/ # High‑level task prompts for WS agents
|
||||
│ ├─ tasks/ # Saved task flows / playbooks
|
||||
│ └─ settings.json # Editor/workbench preferences for this repo
|
||||
├─ scripts/ # CLI scripts (bash/python); dev + ops helpers
|
||||
│ ├─ env/ # venv helpers (create, activate, pin)
|
||||
│ ├─ dev/ # codegen, lint, format, typecheck wrappers
|
||||
│ ├─ ops/ # backup, rotate logs, journalctl, users
|
||||
│ └─ ci/ # sanity checks usable by CI (no runners assumed)
|
||||
├─ configs/ # Centralized *.conf used by services
|
||||
│ ├─ nginx/ # (optional) reverse proxy snippets (host‑level)
|
||||
│ ├─ systemd/ # unit files for host services (no docker)
|
||||
│ ├─ security/ # fail2ban, firewall/ipset lists, tls policy
|
||||
│ └─ app/ # app‑level INI/YAML/TOML configs shared across apps
|
||||
├─ docs/ # Markdown docs (specs, ADRs, guides)
|
||||
│ ├─ 00-index.md
|
||||
│ ├─ adr/ # Architecture Decision Records
|
||||
│ ├─ specs/ # Protocol, API, tokenomics, flows
|
||||
│ ├─ runbooks/ # Ops runbooks (rotate keys, restore, etc.)
|
||||
│ └─ diagrams/ # draw.io/mermaid sources + exported PNG/SVG
|
||||
├─ packages/ # Shared libraries (language‑specific)
|
||||
│ ├─ py/ # Python packages (FastAPI, utils, protocol)
|
||||
│ │ ├─ aitbc-core/ # Protocol models, validation, common types
|
||||
│ │ ├─ aitbc-crypto/ # Key mgmt, signing, wallet primitives
|
||||
│ │ ├─ aitbc-p2p/ # Node discovery, gossip, transport
|
||||
│ │ ├─ aitbc-scheduler/ # Task slicing/merging, scoring, QoS
|
||||
│ │ └─ aitbc-sdk/ # Client SDK for Python integrations
|
||||
│ └─ js/ # Browser/Node shared libs
|
||||
│ ├─ aitbc-sdk/ # Client SDK (fetch/ws), typings
|
||||
│ └─ ui-widgets/ # Reusable UI bits for web apps
|
||||
├─ apps/ # First‑class runnable services & UIs
|
||||
│ ├─ client-web/ # Browser UI for users (requests, wallet, status)
|
||||
│ │ ├─ public/ # static assets
|
||||
│ │ ├─ src/
|
||||
│ │ │ ├─ pages/
|
||||
│ │ │ ├─ components/
|
||||
│ │ │ ├─ lib/ # uses packages/js/aitbc-sdk
|
||||
│ │ │ └─ styles/
|
||||
│ │ └─ README.md
|
||||
│ ├─ coordinator-api/ # Central API orchestrating jobs ↔ miners
|
||||
│ │ ├─ src/
|
||||
│ │ │ ├─ main.py # FastAPI entrypoint
|
||||
│ │ │ ├─ routes/
|
||||
│ │ │ ├─ services/ # matchmaking, accounting, rate‑limits
|
||||
│ │ │ ├─ domain/ # job models, receipts, accounting entities
|
||||
│ │ │ └─ storage/ # adapters (postgres, files, kv)
|
||||
│ │ ├─ migrations/ # SQL snippets (no migration framework forced)
|
||||
│ │ └─ README.md
|
||||
│ ├─ miner-node/ # Worker node daemon for GPU/CPU tasks
|
||||
│ │ ├─ src/
|
||||
│ │ │ ├─ agent/ # job runner, sandbox mgmt, health probes
|
||||
│ │ │ ├─ gpu/ # CUDA/OpenCL bindings (optional)
|
||||
│ │ │ ├─ plugins/ # task kinds (LLM, ASR, vision, etc.)
|
||||
│ │ │ └─ telemetry/ # metrics, logs, heartbeat
|
||||
│ │ └─ README.md
|
||||
│ ├─ wallet-daemon/ # Local wallet service (keys, signing, RPC)
|
||||
│ │ ├─ src/
|
||||
│ │ └─ README.md
|
||||
│ ├─ blockchain-node/ # Minimal chain (asset‑backed by compute)
|
||||
│ │ ├─ src/
|
||||
│ │ │ ├─ consensus/
|
||||
│ │ │ ├─ mempool/
|
||||
│ │ │ ├─ ledger/ # state, balances, receipts linkage
|
||||
│ │ │ └─ rpc/
|
||||
│ │ └─ README.md
|
||||
│ ├─ pool-hub/ # Client↔miners pool + matchmaking gateway
|
||||
│ │ ├─ src/
|
||||
│ │ └─ README.md
|
||||
│ ├─ marketplace-web/ # Web app for offers, bids, stats
|
||||
│ │ ├─ public/
|
||||
│ │ ├─ src/
|
||||
│ │ └─ README.md
|
||||
│ └─ explorer-web/ # Chain explorer (blocks, tx, receipts)
|
||||
│ ├─ public/
|
||||
│ ├─ src/
|
||||
│ └─ README.md
|
||||
├─ protocols/ # Canonical protocol definitions
|
||||
│ ├─ api/ # OpenAPI/JSON‑Schema for REST/WebSocket
|
||||
│ ├─ receipts/ # Job receipt schema, signing rules
|
||||
│ ├─ payouts/ # Mint/burn, staking, fees logic (spec)
|
||||
│ └─ README.md
|
||||
├─ data/ # Local dev datasets (small, sample only)
|
||||
│ ├─ fixtures/ # seed users, nodes, jobs
|
||||
│ └─ samples/
|
||||
├─ tests/ # Cross‑project test harness
|
||||
│ ├─ e2e/ # end‑to‑end flows (client→coord→miner→wallet)
|
||||
│ ├─ load/ # coordinator & miner stress scripts
|
||||
│ └─ security/ # key rotation, signature verif, replay tests
|
||||
├─ tools/ # Small CLIs, generators, mermaid->svg, etc.
|
||||
│ └─ mkdiagram
|
||||
└─ examples/ # Minimal runnable examples for integrators
|
||||
├─ quickstart-client-python/
|
||||
├─ quickstart-client-js/
|
||||
└─ receipts-sign-verify/
|
||||
```
|
||||
|
||||
## Conventions
|
||||
|
||||
- **Languages**: FastAPI/Python for backends; plain JS/TS for web; no Docker.
|
||||
- **No global venvs**: each `apps/*` and `packages/py/*` can have its own `.venv/` (created by `scripts/env/*`).
|
||||
- **Systemd over Docker**: unit files live under `configs/systemd/`, with service‑specific overrides documented in `docs/runbooks/`.
|
||||
- **Static assets** belong to each web app under `public/`. Shared UI in `packages/js/ui-widgets`.
|
||||
- **SQL**: keep raw SQL snippets in `apps/*/migrations/` (aligned with your “no migration framework” preference). Use `psqln` alias.
|
||||
- **Security**: central policy under `configs/security/` (fail2ban, ipset lists, TLS ciphers). Keys never committed.
|
||||
|
||||
## Minimal READMEs to create next
|
||||
|
||||
Create a short `README.md` in each `apps/*` and `packages/*` with:
|
||||
|
||||
1. Purpose & scope
|
||||
2. How to run (dev)
|
||||
3. Dependencies
|
||||
4. Configs consumed (from `/configs/app`)
|
||||
5. Systemd unit name & port (if applicable)
|
||||
|
||||
## Suggested first tasks (Way of least resistance)
|
||||
|
||||
1. **Bootstrap coordinator-api**: scaffold FastAPI `main.py`, `/health`, `/jobs`, `/miners` routes.
|
||||
2. **SDKs**: implement `packages/py/aitbc-sdk` & `packages/js/aitbc-sdk` with basic auth + job submit.
|
||||
3. **miner-node prototype**: heartbeat to coordinator and no‑GPU "echo" job plugin.
|
||||
4. **client-web**: basic UI to submit a test job and watch status stream.
|
||||
5. **receipts spec**: draft `protocols/receipts` and a sign/verify example in `examples/`.
|
||||
|
||||
Reference in New Issue
Block a user