Managing Projects

A project is the top-level container in the Manager. Everything else belongs to a project: the applications you build, the tenants (customer organizations) you serve, the environments you deploy to, the tenant role definitions, language packs, pilets and the project's audit log. Use a project for one product or one product line.

What a project contains

• Applications: defined once at the project level and enabled per tenant. See Managing Applications.
• Tenants: customer organizations. A tenant is not an environment. See Managing Tenants.
• Environments: dev, qas or run deployment targets, with an optional base domain. Machine users and deployments are scoped to an environment.
• Tenant role definitions: the configurable roles tenant members can hold. Every new project is seeded with member, admin and owner. See Access Model.
• Project settings: the base layer of the configuration cascade. See Settings Editor.
• Language packs, pilets and audit logs: project-scoped resources with their own pages.

Creating a project

1. Click Project management in the sidebar.
2. Click New project.
3. In the Create project dialog, enter a Name (unique, up to 100 characters).
4. Check the Slug. It is auto-filled from the initials of the name and must be unique. Maximum 10 characters.
5. Click Create. You land on the new project's page.

The creator is added to the project as owner, and the three default tenant roles are seeded for the project.

The projects list

The Project management page lists every project you are a member of:

Column	Meaning
#	Project slug
Name	Display name
Created at / Created by	Creation metadata
Updated at / Updated by	Last change metadata

Click #, Name, Created at or Updated at to sort (sorting runs on the server). There is no search box on this page.

The project page

Click a row to open the project. The page shows:

• The project dashboard (deployment matrix across environments, tenant application coverage, recent activity).
• A metadata table: Created by, Created at, Editor, Updated at.
• Project members: the users who can open this project in the Manager and their project roles. Adding, re-roling and removing members needs the maintainer or owner role. See User Management.

The sidebar section Project links to the project's sub-pages:

Sidebar entry	Path	What it is
Project details	/<project>	The page above
Project settings	/<project>/settings	Backend and frontend settings for the base layer
Language Packs	/<project>/language-packs	Translations shared by the project's applications
Pilets	/<project>/pilets	Microfrontend packages, see Pilet Management
Audit Logs	/<project>/audit-logs	Activity history, see Audit Logs
Tenants	/<project>/tenants	Customer organizations
Environments	/<project>/environments	Deployment environments
Applications	/<project>/applications	Project-level applications

Renaming a project

Renaming needs the project role maintainer or owner, or the system administrator role. A rename moves the slug, which every Manager URL, deep link and CLI invocation is addressed by.

The UI has no edit form for a project. Use the CLI or the API:

pfy project update <slug> --name "New name"

mutation {
  updateProject(id: "project-uuid", input: { name: "New name" }) {
    id
    name
    slug
  }
}

UpdateProjectInput accepts name and slug only.

Deleting a project

Deleting needs the same authority as renaming: maintainer, owner, or the system administrator role.

Deletion is refused while structural children still exist

Deleting a project is not offered in the UI. Through the CLI (pfy project delete <slug>) or the API (deleteProject(id)), the server counts every child that would refuse the delete and names each one with a count before writing anything: cannot delete project: it still has 2 tenant(s), 1 application(s); delete them first. The blockers are tenants, applications, environments, pilet packages and pilet rollouts. Clear them and the delete goes through.

The project's seeded tenant role definitions do not block it: deleteProject removes them itself, and records their names in the audit row, because once the tenants are gone nothing can read or assign them anyway.

The delete writes an audit row before it removes anything, inside the request transaction, so it is the only surviving record of what the project was called, how many members and language packs it had, and which tenant roles it defined. See Audit Logs.

Configuration inheritance

Project settings are the most general layer. When the Manager resolves the frontend configuration for a (tenant, application) pair it merges, in this order:

Project settings
  → Application settings (module fields only)
    → Tenant settings
      → (Tenant, Application) settings   ← most specific

A layer that leaves a field empty inherits it; a non-empty value replaces (or, for Available* lists and key-value pairs, merges into) what came before. Set shared defaults on the project and override only where a tenant or application needs something different. See Configuration Layers and Settings Editor.

Common tasks

Copy settings from one project to another

Applications, tenants and environments are not cloned with a project; only settings can be copied by hand:

1. Open the source project's Project settings and switch to JSON Editor.
2. Copy the Backend and Frontend JSON.
3. Create the new project.
4. Open its Project settings, switch to JSON Editor, paste, and click Save changes.

The copyApplication and promoteApplication mutations still exist in the schema, carry @deprecated directives naming their replacements, and always return an error; applications are project-level now and there is nothing to copy between tenants. To move per-tenant configuration between two enablements, use pfy application config-copy --from <joinId> --to <joinId>.

Give someone access

Add them as a project member with the lowest role that fits. Any project role lets a user open the project and read it. maintainer and owner are needed to manage members, environments, endpoints, triggers, machine users, pilets, settings and application enablement, and to rename or delete the project itself and any of its applications.

A readonly member can still create a tenant, an application or a language pack: those three mutations are gated on bare project membership. They cannot rename, repoint or delete anything. See Access Model.

Troubleshooting

I cannot see a project

You are not a member. Ask a project maintainer or owner to add you, or a system administrator, who overrides project membership for this and does not need to be a member of the project first.

Settings are not applied to an application

Check the more specific layers: tenant settings and the (tenant, application) leaf override the project. Open the application's or tenant's Settings page and look at the Configuration Layers panel.

cannot delete project

See Deleting a project. The message names each blocker and how many of them there are; clear those and retry. If it says something generic instead ("it is still referenced by other records"), a child relation was added to the schema without being added to the pre-count; report it.

See also

• Managing Applications
• Managing Tenants
• Multi-tenancy: projects, applications, environments and tenants
• Configuration Layers
• Settings Editor