System Architecture
One core engine, multiple interfaces.
The CLI serves humans, the MCP server serves agents, and both call Beam Core for parsing, Figma access, caching, snapshots, simplification, assets, compare, and observability.
Beam Core owns product intelligence: URL parsing, auth resolution, Figma client calls, cache management, snapshot storage, simplification, token planning, assets, compare, and logs.
No direct Figma calls should live outside the core Figma client. No CLI-specific or agent-specific behavior should leak into the core engine.
Cloud services are optional extensions. The Free core must stay useful without hosted accounts, dashboards, billing, or enterprise infrastructure.
Run Sequence
- A human or agent sends a Figma URL to the CLI or MCP server.
- Beam Core parses the URL and resolves local credentials.
- The Figma client fetches node data and rendered images through scheduled, cache-aware requests.
- The snapshot store records source metadata and artifact paths.
- The simplifier produces the implementation brief, token summary, asset list, evidence, and warnings.
- CLI or MCP returns the same core result in human or machine-friendly form.
Expected Output
A healthy architecture keeps all Figma, cache, snapshot, simplification, asset, compare, and evidence behavior inside Beam Core, with thin CLI and MCP interfaces on top.
Files And Artifacts
- packages/core/src/
- packages/cli/src/
- packages/mcp/src/
- .beam/cache/
Next Step
Use the contracts page when adding or changing a field shared by CLI, MCP, cache, or cloud.
Recovery Paths
- If CLI and MCP behavior differ, move duplicated behavior back into Beam Core.
- If Figma calls appear outside the core client, consolidate them before expanding features.
- If cloud becomes required for Free workflows, restore the local-first boundary.
