Architecture

Platform is a Flask API with a Discord bot, a job worker and an MCP server. All four use the same code in core/ and modules/ and the same database.

ProcessesCopy Anchor Link

The database is Postgres in production, or SQLite for a small deployment. Alembic makes the schema.

This diagram shows the processes, their clients and the outside services.

flowchart LR
  dashboard["dashboard/"] --> api["API: main.py, port 8000"]
  web["web/"] --> api
  website["thesoda.io"] --> api
  agents["Apps and agents"] -->|"Bearer plat_..."| mcp["MCP server: mcp_main.py, port 8001"]
  agents -->|"/api/tools"| api
  api --> db[("Postgres or SQLite")]
  mcp --> db
  bot["Discord bot: bot_main.py"] --> db
  worker["Job worker: worker_main.py, Postgres only"] --> db
  api -->|"REST, BOT_TOKEN"| discord["Discord"]
  bot --> discord
  api --> outside["RunPod, Notion, Google, GitHub and other services"]
  worker --> outside

The API does not need the bot. It reads Discord servers, roles and members over Discord's REST API with BOT_TOKEN (core/integrations/discord.py). The Jeopardy routes under /api/bot are the exception: they call the bot's cogs, so they work only when the bot runs in the API process (RUN_BOT_IN_API=true).

LayoutCopy Anchor Link

main.py, bot_main.py, worker_main.py, mcp_main.py   the four entry points
core/          shared code: config, database, jobs, tools, secrets, audit, logs, HTTP hooks, Discord and RunPod clients, hosting providers
modules/       one folder per module, not nested; registry.py mounts the blueprints, manifest.py lists categories, models, jobs and tools
alembic/       migrations
tests/         pytest; tests/contract/ checks every route a client uses
dashboard/, site/   the dashboard and member store, the docs and landing site
deploy/        the RunPod start script and the SQLite to Postgres copy script

core/ imports nothing from modules/. Only the route files (api.py, member_api.py), registry.py, cli.py and the route helpers in modules/auth/ import Flask. make ci checks both with import-linter.

How a request runsCopy Anchor Link

1. Flask-CORS adds the CORS headers for an allowed origin. The list is in main.py, plus CORS_EXTRA_ORIGINS and DASHBOARD_URL.
2. If the path starts with a DISABLED_ROUTES prefix, the API returns 404.
3. modules/registry.py sends the request to the module blueprint. If the module is turned off for the org in the URL, it returns 404.
4. A decorator from modules/auth checks the caller. See Authentication.
5. The view reads the request, calls the module's service.py and returns JSON.
6. Before the response goes out, core/http/request_log.py logs one line, and core/http/audit_hook.py writes each successful change to audit_log.

The org comes from the URL (org_prefix or org_id), or from the machine token. The X-Organization-* headers that older clients send are used only in the request log.

Views get a database session from officer_route, machine_route or member_view in modules/auth/routes.py, or from core.db.session(). Older views call next(db_connect.get_db()) and close the session in a finally block.

ModulesCopy Anchor Link

A module is a folder in modules/ with only the files it needs: service.py for the logic, api.py for the routes, models.py, jobs.py and tools.py. The REST routes, jobs, tools and the bot call the same service.py functions. Writing a module gives the rules and the places to register a module.

Orgs can turn on and off the optional modules: points, storefront, calendar, games, leetcode, godfather, event_webhook, feeds, uptime, knowledge, agents, integrations, accounts and runpod. The list is OPTIONAL_MODULES in modules/organizations/service.py. The Core modules, mcp and submodules among them, are always on. When a module is off for an org, its routes return 404 for the org (module= on officer_route, machine_route or the Mount), its tools are not listed, and its jobs skip the org. With integrations off, the org has no tools of connected services. If games is off for each org of an officer, the /api/bot routes return 404 for that officer. The switches are in Organization.config["modules"]. A module with no entry is on, so an org made before the switch existed keeps the module. A new org gets an entry for each optional module: on for the modules in NEW_ORG_MODULES in modules/manifest.py, off for the others. NEW_ORG_MODULES is empty, so a new org starts with Core only. Officers add and remove modules on the dashboard Explore page, or with flask --app main org modules <prefix> --on x --off y.

Categories, modules and sub-modulesCopy Anchor Link

A category groups modules. A module can read sub-modules.

flowchart LR
  category["Category: Storage"] --> module["Module: knowledge"] --> submodule["Sub-module: submodules/asu"]

CATALOG in modules/manifest.py gives each module a title, a description, what it needs (integration keys or settings) and the sub-modules it reads. CATEGORIES puts each module in one category:

The dashboard sidebar has one section for each category except Core. The routes and tools of submodules need the knowledge module. GET /api/dashboard/<org>/modules returns the catalog with the org's switches and whether each need is connected.

JobsCopy Anchor Link

A module declares a job in its jobs.py with @job(name, cron=..., retry=...) from core/jobs.py. Code starts a job with jobs.defer(name, **kwargs). Each module README lists its jobs. flask --app main jobs list lists all of them.

• On Postgres, defer adds a row to the Procrastinate queue. The worker runs the job, tries it again if it fails, and runs the periodic jobs.
• On SQLite, there is no queue. defer runs the job in a thread of the calling process. A thread in the API runs the periodic jobs, and worker_main.py stops.

JOBS_BACKEND=inline|procrastinate sets the choice. The tests use inline. JOBS_SCHEDULER=false stops the thread that runs periodic jobs with the inline backend; the tests set it, so no periodic job changes rows during a test. Each run of a job with audit=True (the default) is written to audit_log.

Tools and the MCP serverCopy Anchor Link

Apps and agents read and change Platform data through tools. A module declares a tool in its tools.py with @tool from core/tools.py. Platform serves each tool two ways:

• Over MCP (streamable HTTP) from mcp_main.py, at http://<host>:8001/mcp.
• Over HTTP from the API: GET /api/tools lists the tools, and POST /api/tools/<name> calls one with the arguments as the JSON body.

Both need a machine token: Authorization: Bearer plat_.... The mcp module is Core, so it is always on. A caller sees only the tools that its token scopes allow and whose module its org has turned on. The MCP card on the Tokens page of the dashboard shows the server and the header. An unknown tool and a refused tool both return 404, so a token cannot find tools it may not use. A tool always acts on the caller's org. It has no org argument.

A tool marked confirm changes or deletes something that is hard to undo. It runs only when the call has confirm=true. Without it, nothing changes and the result has confirm_required, the arguments, and for apps.deploy and apps.rollback the dry run. An agent shows that to a person, then calls again with confirm=true. Over MCP, read tools have readOnlyHint and confirm tools have destructiveHint.

No tool returns a secret value or a webhook URL. tokens.create returns the new token once. It gives only the scopes and limits of the calling token. A write tool that takes ids changes up to 100 rows in one commit; if one id is missing, nothing changes. To send many calls in one request, use batch with {"calls": [{"tool", "arguments"}], "stop_on_error"}. Its result has one entry for each call: tool, ok, result or error, and status.

The flows that need a browser have no tool: the OAuth sign-in to an integration, the ASU sign-in, file upload and download on a pod, and the Godfather CLI sign-in. Superadmin routes and member routes have no tool.

Each call, allowed or refused, is a row in audit_log with action=tool <name>, source=mcp or api, and the token as the actor. A call that waits for confirm has details.confirm=pending. The MCP server keeps no session state, so you can run more than one. Start it with docker compose --profile mcp up -d mcp.

Outside servicesCopy Anchor Link