Skip to content

Architecture ​

If you are new to PhillipCLI, read the Introduction first. The platform has four components. Two run on your machine, two run online, and data only flows one way: from your machine outward. After reading this page, you will understand why online services never need access to your machine.

Architecture diagram. On your machine: Phillip, Claude Code with Guardrails, and Bandum. Online: Tara, Ryoma and Grafana. GitHub or GitLab holds the source data. Your machine pushes data out; online services never call back into your machine.On your machineOnlinePhillipph CLI and VS CodeClaude CodeGuardrails vets commandsBandumTask board, testingTaraResource library, PortalRyomaFlow and AI metricsGrafanaInternal ops dashboardsGitHub or GitLabSource of truth: issues, labels, PRs, testcase filesruns via phInstall resources, sign inFiltered telemetrydashboardsTasks, labels, test filesReads task progress

Swipe sideways to see the whole diagram.

Arrows show the direction data moves. Phillip and Bandum call out; online services never call back into your machine.

The four components ​

Phillip runs on the user's machine. It is the ph CLI plus a VS Code extension. It installs resources from Tara, runs Claude Code with the project's configuration, and receives and hands off tasks. Bandum also runs on the user's machine. It holds the task board, test cases, acceptance testing, and approvals, and Phillip downloads and starts it for you.

Tara and Ryoma run online. Tara is the resource registry. It handles sign-in, signing, and the review of the official store, and it hosts the Portal and the Knowledge base. Ryoma collects AI session metrics and delivery progress for each organization. Customers read their dashboards on the Projects pages of the Portal.

Users fall into two groups. Devs and Testers use Phillip and Bandum on their machines. BAs, POs, and PMs need only a browser to reach the Tara Portal and the Bandum website.

Phillip ​

Phillip is the single entry point on your machine. You keep working in VS Code with Claude Code as usual, and Phillip prepares the environment behind the scenes.

The ph setup command signs you in to Tara, applies a harness to the project, and connects GitHub or GitLab. The ph tara add and ph tara install commands install the exact versions locked in phillip.lock. Before loading anything, Phillip checks the sha256 and the digital signature. When you run Claude Code through ph, Phillip turns on telemetry to Ryoma. What it sends is listed in Data collected.

The Guardrails hook server is also part of Phillip and runs on your machine. See Guardrails tiers. To talk to GitHub, GitLab, or other tools, Phillip loads connector plugins (kits). Phillip's core contains no provider-specific code.

Bandum ​

Bandum handles acceptance: an agent or dev does a task, and a Tester approves it or returns it. It runs on the user's machine with SQLite, or PostgreSQL in Docker. ph bandum ui downloads and starts it for you.

Bandum doesn't hold the source data. Tasks are issues, statuses are labels, and test cases and test results are files in the repo. If you delete Bandum's data, you can rebuild it from the repo. The file formats are in Bandum format.

Tara ​

Tara is the shared online hub, and everything you can do on Tara you can also do from Phillip.

Tara holds the resource registry, which contains six resource types. Every version is immutable. A resource must pass automated checks before it is signed and released, and the official store adds a review by platform staff. See Review criteria. Tara also handles sign-in and organizations (Roles and permissions). It keeps the Knowledge base for each organization and project, which agents access through MCP (MCP tools). The Portal is the web interface for discovery, organization settings, and the Projects section, where the metrics come from Ryoma.

Tara serves a marketplace that follows the Claude Code standard, so resources install into Claude Code like any other plugin.

Organizations and projects ​

Tara is multi-tenant. An organization is the customer unit: it has members with roles, a plan with seats, its own resource store (<org>/<name>), and its own Guardrails. A project belongs to exactly one organization and stands for a product or repo, with its tasks, metrics, and Guardrails. One account can belong to several organizations, and Phillip keeps one token for each.

Data is isolated per organization twice: the application passes the organization from your token to every query, and the database (Postgres Row-Level Security) returns only that organization's rows. The official store (aiforge/<name>) and public community resources are shared and read-only for everyone. Resource names carry the owner, an organization or a person, as in acme/skill-review or an/skill-notes; a person's personal store is private to them. See Six resource types.

Ryoma ​

Ryoma runs per organization: every metric is tagged with the organization from your token, and every query filters by it. Ryoma receives Claude Code's OpenTelemetry telemetry and reads task progress from GitHub or GitLab. From these it computes metrics based on the Flow Framework and the AI measurement framework. Ryoma stores only counts and metadata, never the content of prompts or responses. For how to read the metrics, see Measurement.

Which way does data flow? ​

Data only flows out from the user's machine. Online services never call into your machine or into the local Bandum.

DirectionContentAuthentication
Phillip to TaraSign-in, downloading signed packages, submitting, viewing the Knowledge baseYour Tara token
Phillip to RyomaAI session telemetry, Guardrails events (metadata only)Your Tara token; Ryoma attaches the identity on the server side
Phillip, Bandum to GitHub/GitLabRead and write issues, labels, PRsYour own token
Ryoma to GitHub/GitLabSync tasks to compute metricsService token, read-only
Tara to RyomaMetrics shown in the PortalService token, read-only

Notifications through Telegram, email, Slack, or Zalo go out from Tara, Ryoma, and Bandum through the notify kit plugin. They contain only metadata such as the task ID, title, and link.

GitHub and GitLab hold the originals ​

The platform doesn't keep the original task or the source code. A task is an issue, a sprint is a milestone, and the owner is the assignee. The status is a status: … label, and the decision to approve or return is a PR review. Test cases, acceptance results, and evidence are files on the PR's branch.

Ryoma and Bandum keep only copies for display and computation. If a copy is lost, sync again from the repo.

Where plugins run ​

A kit installed on your machine runs in your process with your permissions, so Phillip loads it only when the signature is valid. On the Tara, Bandum, and Ryoma servers, the same kit runs in a Node process with node --permission. There it can read only the plugin directory and can't see the service's secrets. For how to write a kit, see Write kits.

Next steps ​