Projects & Files

Projects are one of the clearest examples of how NuxtBase models product data.

They are:

• tied to the active organization
• available only to verified users
• readable by organization members
• editable by organization managers

The Shipped Project Model

The dashboard includes:

• a project list at /dashboard/projects
• a project detail/settings page at /dashboard/projects/[id]
• file attachments on the project detail page

Project listing and detail reads require:

• a verified session
• an active organization
• a project that belongs to that organization

Create, update, delete, upload, and file removal actions add one more rule:

• the current user must be an organization owner or admin

Read Access Versus Write Access

This split is important in the shipped template:

• GET /api/projects only requires a verified session and active organization
• GET /api/projects/[id]/files also only requires a verified session and active organization
• write endpoints use organization-manager guards

So members can view project data, but they do not get create or edit controls in the dashboard UI.

Project Lifecycle

The normal flow is:

1. open the project list for the active organization
2. create a project from the modal
3. open the project detail page
4. update name or description
5. upload or remove files
6. archive the project through the delete action

Project deletion is a soft-delete pattern. The record gets a deletedAt timestamp and status changes to archived, instead of being hard-removed immediately.

File Attachments

Project files are stored as file assets plus attachment references.

The important behavior is:

1. upload stores the file through the configured storage provider
2. the app creates a fileAttachmentRef that links the asset to the project
3. file listing resolves project refs back to stored assets
4. deletion removes the ref and soft-deletes the file asset

That means storage configuration lives in setup/storage-setup, but project behavior lives here.

Audit And Webhook Side Effects

Project mutations are not isolated CRUD calls.

The shipped code also:

• writes audit logs for create, update, delete, upload, and file delete actions
• dispatches outbound webhook events for project.created and project.deleted

If you customize project behavior, those side effects need to stay aligned.

One Easy Misread

The billing page shows a free-plan project usage indicator of 3, but the project APIs shown in the current template do not enforce a hard server-side project cap.

Treat that as a product UI signal, not as proven API enforcement, unless you add your own limit logic.

Caution

If file uploads fail, do not start in the project code first. Check your storage provider setup and upload path handling before debugging the project UI.