BlackRoad OS Repository Snapshot

1. Repo Structure Summary

backend/: FastAPI backend with routing, models, and the canonical backend/static UI bundle served by the API layer.
backend/static/: Windows 95-inspired single-page interface served by FastAPI (/ and /static).
blackroad-os/: Older standalone static build (HTML/JS/assets) that appears superseded by backend/static but still present in the repo.
agents/: Python agent library with base abstractions, categories, templates, and tests.
sdk/: Language-specific SDKs (Python/TypeScript) for integrating with the platform.
docs/, scripts/, CI assets (.github/workflows), and root-level guidance/vision documents provide deployment, security, and integration references.

Framework: FastAPI with CORS middleware, mounted static files, and /health endpoint; routes imported from many service modules (auth, email, social, video, files, blockchain, AI chat, integrations, v0.2 capture/identity/notifications/creator/compliance/search).
Lifespan creates DB tables via SQLAlchemy async engine and rotates wallet keys on startup; shutdown closes Redis and disposes DB connections.
Settings default to SQLite for local/dev while .env template targets PostgreSQL/Redis; ALLOWED_ORIGINS, JWT secrets, and cloud keys are environment-driven.
ENV vars referenced include database URLs, Redis URL, SECRET_KEY/JWT settings, wallet master key, OpenAI key, S3 credentials, SMTP settings, blockchain tuning, Stripe keys, Twilio/Slack/Discord/Sentry tokens, Railway config, and more (see .env.example).
Health check: /health returns JSON with status/timestamp; OpenAPI docs served under /api/docs.

Primary SPA lives in backend/static/index.html with inline assets, delivered directly by FastAPI root route for API co-location.
Additional legacy UI in blackroad-os/index.html with supporting JS/assets suggests duplication/possible drift from canonical static bundle.
No build tooling; vanilla HTML/CSS/JS per root README instructions.

Backend includes auth router providing JWT-based auth with access/refresh expiry settings; relies on SECRET_KEY/ALGORITHM env vars.
New identity-centric routes included via identity_center router (v0.2 APIs) though implementation status should be validated per-router.

Stripe router is included in app.main; .env.example declares STRIPE_SECRET_KEY and STRIPE_PUBLISHABLE_KEY, but actual wiring/state of routes should be confirmed in stripe module before production use.

Agent library lives in agents/ with base agent/executor/registry, 10 category folders, templates, and tests; advertised as 200+ agents.
AI chat router loaded in FastAPI alongside OpenAI API key in settings, but external provider configuration depends on env vars.

GitHub Actions workflows present for CI (ci.yml), backend tests, deploy, Railway automation/deploy.
Dockerfile and docker-compose in backend/; Railway configs (railway.toml/railway.json) at repo root.
Tests exist under backend/tests/ covering auth, blockchain, miner, integrations, dashboard, VS Code router; test results not run in this snapshot.

Missing or incorrect env vars (DB/Redis/SECRET_KEY/Stripe/OpenAI/etc.) will break startup or integrations.
Legacy blackroad-os static bundle could diverge from backend/static, leading to inconsistent deployments if wrong entry point is published.
SQLite defaults in app.config.Settings may hide Postgres/Redis issues until production; migrations/alembic configs exist but runtime auto-creates tables at startup, risking schema drift.
External integration routers (Stripe/Twilio/Slack/Discord/etc.) may be stubbed or unconfigured; deployment without keys will fail requests.
CI presence suggests expectations for tests; failing/long-running suites could block PRs if dependencies not installed.

Validate .env contents against app.config.Settings using scripts/railway/validate_env_template.py before deployment to ensure secrets alignment.
Consolidate on backend/static as the authoritative UI and document deprecation of blackroad-os to reduce confusion.
Add explicit status documentation per router (implemented vs stub) to set expectations for integrations like Stripe/Twilio.
Switch default settings to rely on env vars (or fail-fast) in non-dev environments to avoid accidental SQLite/localhost usage.
Run and document backend test results in CI badges to highlight current health.

Use main for stable releases tied to Railway deploys; require CI pass and env validation before merge.
Maintain develop (or feature branches) for active work on routers/agents/UI; protect with PR checks and targeted reviewers per area (backend vs agents vs static UI).
When touching integrations, gate merges behind mocked tests plus manual smoke checks against a staging environment with representative secrets.