Skip to main content
Projects are the core of Buildstory — they showcase what you’re building, track your progress, and can be linked to events like hackathons.

​
Creating a Project

Start a new project from the Projects page or during event registration:
1

Navigate to /projects/new

Click “New project” from the Projects tab in the app sidebar
2

Fill out project details

Provide name, description, starting point, goal, and optional URLs
3

Customize project URL

Auto-generated slug from name, or click “Customize URL” to set your own
4

Submit

Server action validates fields, creates project row, and optionally links to event

​
Project Form Fields

​
Required Fields

  • Name - Project title (used to auto-generate slug)
  • Description - What does it do? (supports simple markdown)

​
Optional Fields

  • Starting point - Choose “New project” (from scratch) or “Existing project” (building on something)
  • Goal - What you want to accomplish (supports markdown)
  • GitHub URL - Link to repository
  • Live URL - Deployed project URL
Descriptions and goal text support simple markdown formatting for bold, italic, and links.

​
Project Slugs

Every project gets a unique slug for its URL: 
buildstory.com/projects/{slug}

​
Slug Generation

  1. Auto-generated - Derived from project name:
    • Lowercase
    • Replace non-alphanumeric with hyphens
    • Strip leading/trailing hyphens
    • Max 60 characters
  2. Custom slug - Click “Customize URL” to set manually:
    • Lowercase letters, numbers, hyphens only
    • Real-time availability check (debounced 400ms)
    • Must be unique across all projects

Slug validation

Server action checkProjectSlugAvailability runs before creation/update

Visual feedback

Green checkmark (available), red X (taken), spinner (checking)

​
Project Visibility

Projects can be public or event-linked:
  • Standalone projects - Created via /projects/new, visible on your profile
  • Event projects - Linked to hackathons via eventProjects junction table
  • Filtering - Public queries filter by event and exclude projects owned by banned/hidden profiles
The getProjectBySlug query includes project members and event links via Drizzle’s relational with syntax.

​
Editing Projects

Project owners can edit any field after creation:
1

Navigate to project detail page

Visit /projects/{slug} and verify you’re the owner
2

Click Edit button

Top-right corner shows Edit and Delete buttons for owners only
3

Update fields in /projects/{slug}/edit

Shared ProjectForm component handles both create and edit modes
4

Save changes

updateProject server action enforces ownership via profile ID check

​
Ownership Checks

All mutation actions verify project.profileId === currentUserProfileId:
  • updateProject - Edit project fields
  • deleteProject - Remove project and cascade cleanup
  • Team actions - Invite, revoke, remove members

​
Deleting Projects

Owners can delete projects with confirmation: 
// Cascade cleanup in transaction:
1. Delete projectMembers
2. Delete teamInvites
3. Delete eventProjects
4. Delete projects row
Deletion is permanent and cascades to all related records (members, invites, event links).

​
Linking Projects to Events

Projects can be submitted to events (like hackathons):

​
During Onboarding

  • Hackathon registration flow creates project and links it via eventProjects table
  • Junction record stores eventId, projectId, and submittedAt timestamp

​
Standalone Creation

  • Projects created outside events can be linked later if an eventId is provided
  • Query getHackathonProjects filters by event slug and includes team members

Event badge

Project detail pages show event badges for all linked events

Unique constraint

One project can only be linked to each event once (unique on eventId, projectId)

​
Project Detail Pages

Public project pages at /projects/{slug} display:
  • Header - Name, starting point badge, event badges
  • Description - Markdown-rendered project description
  • Goal - Highlighted goal text (if set)
  • Links - GitHub and Live site links
  • Team section - Owner, members, and invite UI (owner-only)
  • Actions - Edit and Delete buttons (owner-only)

​
Team Section

See the Teams documentation for details on inviting teammates and managing project members.

​
Server Actions

All project mutations use server actions in app/(app)/projects/actions.ts:
  • createProject - Insert project, optionally link to event, fire Discord webhook
  • updateProject - Update fields with ownership check
  • deleteProject - Cascade cleanup in transaction, revalidate paths
  • checkProjectSlugAvailability - Real-time slug uniqueness check
Each action:
  1. Authenticates via Clerk auth()
  2. Calls ensureProfile() to get profile ID
  3. Validates inputs
  4. Performs database operation
  5. Catches errors and reports to Sentry
  6. Returns { success: boolean, error?: string, data?: T }

Build docs developers (and LLMs) love

Get started for freeTalk to us