Components
The Components page of a project: the web app, the API, the mobile apps and the services it is made of, each with a slug, a kind, a tech stack and an owner; adding, editing, archiving, restoring and deleting them.
By the end of this page you will have written down what a project is made of, know every field a component carries and what reads each one downstream, and know how a component is put away, brought back and, when nothing runs it any more, deleted.
A project is rarely one program. The customer portal is a web app, an API behind it, an iPhone app and an Android app, a nightly import service and the platform they all run on. Each of those is a component: a named application with a kind, a slug, the technologies it is built with and the person who answers for it. Environments say which component they run, stories and requirements will tag the components they touch, releases will carry a version per component and test runs will name the one under test, so the record every later phase reads starts here.
Before you begin
| You want to | You need |
|---|---|
| Open the Components page | component:view-any on the project. Every staff role has it; a client guest is not shown the page. |
| Add a component | component:create, through your role on the project or your team role, or to own the team. |
| Edit, archive or restore one | component:update. |
| Delete one | component:delete, and no environment may still run the component. |
| Name an owner | The owner to be a member of the team; invite them on the Members page first. |
The page lives under a project: open the project from the selector or the registry and choose Components in the sidebar's Selected Project group. The entry is badged with the number of live components.
Read the components
The table lists one component per row, in the project's order:
| Column | What it shows |
|---|---|
| Component | The name, with the slug beneath it in monospace. Press the name to open the detail flyout. An archived component carries an Archived badge. |
| Kind | What the component is: a web app, an API, a mobile app, a service and so on, with its icon. |
| Stack | The first three technologies it is built with, and a count of the rest. |
| Environments | How many environments run the component. |
| Owner | The team member who answers for it, or Unowned. |
| Updated | How long ago the record last changed. |
| Row menu | View Component, Edit Component, Archive Component or Restore Component, Activity, Delete Component. |
Sort by component, kind or updated by pressing a column heading; press it again to flip the direction. Above the table, narrow the list with the search box (words in the name or the slug), the kind list and the Archived switch, which shows archived components instead of live ones. The filters travel in the page address, so a filtered list can be shared; Clear Filters on the empty state drops them all.
Add a component
- Press New Component.
- Type the Name: what the team calls this application, such as Customer Web App or Public API. The name is unique within the project.
- Pick the Kind. A web app, an API or a service starts on the house stack: the moment you pick one of those kinds with an empty stack, the Tech Stack field is filled with Laravel, Livewire, Flux, Tailwind, PostgreSQL and Valkey, ready to be trimmed or extended.
- Leave the Slug empty unless you want a particular one. It is derived from the name
(
customer-web-app), and when that is taken a numbered variant is used. - Describe what the application does and who uses it in the Description, and name the Owner if one is agreed.
- Press Create Component.
The component appears in the table at once and component.created goes out to every endpoint
subscribed to it.
A name is all it needs
Everything else has a default or can follow later. Heimdall reads the tech stack when it drafts stories, tests and estimates for the component, so filling it in early pays off, but an empty stack never blocks anything.
Open a component
Press a component's name, or View Component in its row menu, to open the detail flyout: the name with the kind beside it, then the Identity block (name, slug, kind), the Stack and Owner block, the Description as written, the Runs In list of the environments that run the component with their kind, address and health, and the created and updated stamps. From the flyout, Edit, Archive or Restore, Activity and Delete are one press away.
A link such as /projects/<project>/components?show=<id> opens the page with that component's
flyout already open; notifications and Heimdall's buttons use it.
Edit a component
- Press Edit Component in the row menu, or Edit in the flyout.
- Change what you need. The same rules as adding apply: the name stays unique within the project, a typed slug must be free, the owner must be a member of the team.
- Press Save Changes.
Every change travels as component.updated with its old and new values. An edit that changes
nothing announces nothing.
Archive, restore and delete
- Archive Component takes the component out of the default view. Its environments and its history are kept and stay readable; switch on Archived above the table to find it. Use it for the admin tool that was retired or the mobile app the client dropped from scope.
- Restore Component brings an archived component back into the default view.
- Delete Component removes the component with its activity history. It is refused while an environment still runs the component: archive the component instead, or move those environments to another component first. The confirmation names the consequence; there is no undo.
All the fields
What happens next
- Every add, edit, archive, restore and delete is written to the component's activity history with who did it and where from.
- The
component.created,component.updated,component.archived,component.restoredandcomponent.deletedevents go out to every endpoint subscribed to them. - An environment can name the component it runs, and a component with environments cannot be deleted until they are moved or removed.
- Stories, requirements, releases and test runs will name components as those modules land, which is why the slug stays fixed while the row exists.
Heimdall on this page
Heimdall reads the components through the same tools the MCP server offers and carries the open project as its context, so a question needs no key.
Shaping components is a person's work: Heimdall and an agent over MCP read the record and never write to it.
From the API and MCP
Components API
List, get, create, change, archive, restore and delete components over REST.
list_components and get_component
The two MCP tools that read a project's components as the token sees them.
Permissions
| Action | Permission |
|---|---|
| See the components | component:view-any |
| Open a component | component:view |
| Add a component | component:create, or owning the team |
| Edit, archive or restore | component:update, through a project role or a team role |
| Delete a component | component:delete, and no environment may run the component |
Frequently asked
Related
- Environments — where each component runs
- The project overview — the project the components belong to
- Activity log — where every change is recorded
component.*webhook events
How is this guide?
Last updated on
The Project Overview
Opening a project from the selector, the registry or a Heimdall button; what the overview shows: the key, status and health, the lifecycle strip, the Heimdall suggests rail, the client, dates, leads, budget, description and recent activity; and what a client guest sees of it.
Environments
The Environments page of a project: development, staging, UAT and production with their addresses, branch and flags; the scheduled health check; freezing changes; and what a client guest sees of it.