Internal reference

For botso.ai engineers building the platform, client dashboard, and mobile apps. Not for external distribution.

This page describes internal repo layout and ops. Share API Documentation and API Howto with partners instead.

Architecture

client_dashboard_v1 (React SPA) │ OAuth password grant + Bearer token ▼ dashboard_v2 (Laravel) ──► /api/v1/botso/* │ Passport, permissions, org context ├── botso_platform DB (orgs, pools, tickets, payouts) ├── botso_club_* tenant DBs (optional per-org GDPR) └── v2_baguette_positions (trading session / PnL reads) api/flask_api.py + botso_console.py ──► /api/botso/* (dev JSON mirror, NO AUTH) api/flask_api.py ──► /api/* (operator trading analytics — separate product)

Repositories & key paths

Path	Role
`dashboard_v2/routes/api.php`	Canonical route list — update external docs when this changes
`dashboard_v2/app/Http/Controllers/Api/V1/BotsoConsoleController.php`	Pool/ticket/payment logic
`dashboard_v2/app/Http/Controllers/Api/V1/AuthController.php`	Login, client credentials, profile
`dashboard_v2/app/Services/BotsoOrganizationContext.php`	Org resolution (subdomain, header, query)
`client_dashboard_v1/src/api/client.js`	Reference API consumer
`botso.ai/docs/PLATFORM_REFERENCE.md`	Product/business model (not API)
`botso.ai/external/`	This documentation site
`dashboard_v2/docs/TENANT_ROLLOUT.md`	Per-club DB provisioning

Local setup

Laravel API

dashboard_v2

cd dashboard_v2
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan db:seed
php artisan passport:install
php artisan serve

.env highlights:

BOTSO_CORS_ORIGINS=http://localhost:5173
BOTSO_TENANT_BASE_DOMAIN= — set for subdomain tenant routing
BOTSO_PASSWORD_CLIENT_SECRET / BOTSO_SERVICE_CLIENT_SECRET — optional fixed OAuth secrets

Client dashboard

client_dashboard_v1

VITE_API_URL=http://127.0.0.1:8000/api
VITE_OAUTH_CLIENT_ID=1   # from oauth_clients table

Demo data

Artisan

php artisan botso:fresh-demo

Permission matrix

Permission / gate	Effect
`botso_access`	All authenticated `/v1/botso/*` read routes
`botso_manage`	Platform-wide write (assign, fund, settle) + bypass org admin check
`botso.org.manage` middleware	Org membership role `admin` or `owner`, OR `botso_manage`
`user_management_access`	Bots list, trade history, late90s analytics
`trading:read`	`/v1/trading/*` operator API (separate from botso product)

Seeded roles: admin and operator have botso_access + botso_manage; viewer is read-only.

Regression script: dashboard_v2/scripts/test_botso_authorization.php

Multi-tenant rollout

Organizations can use a dedicated MySQL database (botso_club_{slug}) for member PII while the platform registry stays on botso_platform. See dashboard_v2/docs/TENANT_ROLLOUT.md for:

php artisan botso:provision-tenant {slug}
Subdomain routing via BOTSO_TENANT_BASE_DOMAIN
Demo tenant credentials

Flask mirror (dev only)

api/botso_console.py serves /api/botso/* from botso_data/platform.json with no authentication. Path prefix differs from Laravel (/api/botso/ vs /api/v1/botso/).

Do not point production partners at the Flask mirror. External documentation describes Laravel /api/v1/* only.

Testing

php dashboard_v2/scripts/test_botso_authorization.php — 19 auth/permission checks
Manual: login as admin@botso.ai and client@botso.ai via client dashboard
Partner contract: diff routes/api.php against botso.ai/external/v1/index.html when shipping API changes

Future: OpenAPI

Generate botso.ai/external/openapi/botso-v1.yaml from Laravel routes for Postman import (aligned with Future Ticketing partner workflow).

Maintaining external docs

Route added/changed → update botso.ai/external/v1/index.html
Auth or org behavior changed → update howto.html and mobile.html
Product model changed → update botso.ai/docs/PLATFORM_REFERENCE.md (separate from API docs)
Deploy static botso.ai/external/ to CDN (e.g. external.botso.ai)