AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents
icon: 📂
Projects
A Project is the workspace within a platform where flows, connections, tables, and other resources live. Every platform has at least one, always scoped via platformId. CE gives a single user one personal project; the EE ee-projects module extends this with team projects, limits, and admin CRUD. All editions.
Entity & terms
projectentity:ownerId,platformId,displayName,type,icon(jsonb{ color }),externalId(nullable, for embedding mapping),maxConcurrentJobs(nullable cap),releasesEnabled,metadata,poolId(FK concurrency_pool),deleted(soft-delete timestamp). Unique(platformId, externalId)where not deleted.- ProjectType:
PERSONAL(auto-created on signup, one per user per platform) orTEAM(EE multi-member). - Relations (one-to-many): flows, files, folders, events, appConnections, tables, fields, records, cells, tableWebhooks.
Service methods
create({ displayName, ownerId, platformId, type, callPostCreateHooks?, postCreateContext?, ... })— random icon color, firesprojectHooks.postCreate.postCreateContextcarriesalertReceiverEmailfor auto-subscribing an alert receiver on team projects.update— TEAM allowsdisplayName+icon; PERSONAL allows neither.getOne/getOneOrThrow,getAllForUser(admins see all platform projects, members see assigned),getUserProjectOrThrow(CE list),getProjectIdsByPlatform,countByPlatformIdAndType(limit enforcement).
Endpoints (CE level)
GET /v1/projects— CE returns personal project only.GET /v1/projects/:id— single project.POST /v1/projects/:id— update display name + metadata.
Gotchas
projectHooks.postCreateis where EE creates the associatedProjectPlan, sets piece filters, and auto-subscribes an alert receiver (owner email for personal,context.alertReceiverEmailfor team).- Soft-deleted projects stay in DB; a background job hard-deletes them.
- Raw SQL on
projectmust add"deleted" IS NULLitself. TypeORM adds it only to repository queries, so a rawdatabaseConnection().queryor a join throughprojectreturns soft-deleted projects, names included. Usage name lookups (ai-usage-names.ts) hit this. - A default project is a flag on the project,
project.isDefault(see decision 000051). The database only allows it on team projects (chk_project_is_default_team). Admins set it per project withPOST /v1/projects/:idandisDefault; only platform admins and API keys can, and a plan without project roles getsFEATURE_DISABLED(checked in the controller; the service only takesenforceDefaultGuard). There is no cap on how many defaults a platform has; the platform response reads them in cursor pages of 100, so no single query is unbounded. The platform response lists the live team projects with the flag asdefaultProjectIds, oldest first. The order matters, because the invite dialog preselects the first default. - The web project collection never sends
isDefaultwhen it saves other project settings, so a stale cache can't undo another admin's change. Defaults are only changed throughprojectCollectionUtils.useSetDefaultProjects. - A soft-deleted project keeps its flag until the hard delete; reads skip deleted rows. A default project can't be deleted from the app while it is a default: remove it on Roles & Access first (see decision 000049). API-key deletes, SCIM group deletes, and plans without project roles still delete it. The app check is part of the soft delete (
AND "isDefault" = false), not a read before it, so a project another admin makes a default mid-delete is still refused. - Default projects only apply when a user is created; existing members are never backfilled or removed (see decision 000050). Only team projects of the same platform, and only on plans with
projectRolesEnabled. On the server read them withplatformService.listDefaultProjectIds; in the web, throughplatformHooks.useNewMemberSettings(), which applies the plan gate (newMemberSettingsUtils.activeDefaultProjectIds). - The personal projects switch lives on Roles & access, not the Projects page, and never depends on default projects. What guarantees a new Member a project is either their personal project or the invite: with personal projects off, the platform invite dialog requires a project for Members (see User Invitations).
- Saved settings are not the effective ones. Without
projectRolesEnabled, a savedautoCreatePersonalProjects: falseis kept but ignored: new members still get a personal project, and the saved "off" applies again after an upgrade. Read it throughnewMemberSettingsUtils.personalProjectsActive, never the raw field. - The switch only creates personal projects at sign-up.
getOrCreateWithProjectmakes one when the user row is created, never later, so people who joined while it was off have none. Turning it on can also callPOST /v1/personal-projects/create-missing, which turns the switch on and queues thecreate-missing-personal-projectssystem job in one request (putting the switch back if queuing fails). The job works in batches of 50 under a short per-platformdistributedLock, stops as soon as the switch is off again, and gives active, non-embedded (provider != JWT) members without a live personal project one each. It saves its cursor on its own BullMQ job after every batch (job.updateData, found through a job id built fromplatformId+runId, the same pattern asdeleteFlowHandlerandhardDeleteProjectHandler), and is queued with 10 attempts, 5 minutes apart, so a crashed attempt resumes after the last member it reached instead of re-scanning. If a project's post-create hooks fail, that project is deleted and the member is recorded; at the end the job saves only those members and fails the attempt, so the retry handles just them. Nothing re-creates a personal project an admin deletes later, and turning the switch off never deletes any.
Key files
Entry point: projectService, a log-taking factory in project-service.ts that every project read and write routes through.
packages/server/api/src/app/project/— core service, TypeORM entity, repo, hooks, worker controllerpackages/server/api/src/app/ee/projects/— the whole/v1/projectsHTTP surface plus members, roles, releases, planspackages/core/shared/src/lib/management/project/—Project,ProjectPlan,ProjectIconand request schemaspackages/web/src/features/projects/components/— project switcher, platform switcher, create and edit dialogspackages/web/src/features/projects/stores/— current-project store
Paths verified 2026-07-17. An earlier version pointed at project/project-controller.ts; that file is gone and the /v1/projects routes now register from ee/projects/platform-project-module.ts.