Add projects to the front end

[joelamouche]

• Create a page dedicated to projects
• Each project has name and description, is owned by a user (profile) and editable/deletable by a user that owns it
• Probably makes sense to make projects a bunch of cards

PLEASE submit high level design proposal for this

[pheobeayo]

Can I take up this issue?

[joelamouche]

Sure thing! Pls submit your design proposal before you start working on it

[pheobeayo]

Sure thing! Pls submit your design proposal before you start working on it

Okay, I will submit a design proposal

[pheobeayo]

@joelamouche

High-Level Design Proposal: Projects Feature

Overview

This proposal outlines the implementation of a dedicated Projects page for the Guild Genesis platform. The feature will allow users to create, manage, and browse projects within the guild ecosystem, following established patterns in the codebase and integrating with the existing backend API.

File Structure

New Files to Create

src/
├── pages/
│   └── projects.astro (NEW)
├── components/
│   ├── pages/
│   │   └── ProjectsPage.tsx (NEW)
│   └── projects/ (NEW folder)
│       ├── ProjectCard.tsx
│       ├── CreateProjectModal.tsx
│       ├── EditProjectModal.tsx
│       └── DeleteConfirmationDialog.tsx

This structure follows the existing patterns:

• pages/*.astro → Page entry points (like badges.astro, profiles.astro)
• components/pages/*Page.tsx → Main page components (like BadgesPage.tsx, ProfilesPage.tsx)
• components/[feature]/ → Feature-specific subcomponents (like profiles/, badges/)

Backend Integration

API Endpoints

GET    /api/projects          // List all projects
POST   /api/projects          // Create project
GET    /api/projects/:id      // Get single project
PATCH  /api/projects/:id      // Update project
DELETE /api/projects/:id      // Delete project

Data Model

interface Project {
  id: string;
  name: string;              // max 100 chars
  description: string;       // max 500 chars
  ownerAddress: string;      // Ethereum address
  createdAt: string;         // ISO date string
  updatedAt: string;         // ISO date string
}

Component Architecture

1. projects.astro - Page Entry Point

Minimal Astro page following the exact pattern from badges.astro:

---
import Layout from "@/layouts/Layout.astro";
import ProjectsPage from "@/components/pages/ProjectsPage";
---

<Layout title="Projects - The Guild Genesis">
  <div class="min-h-screen bg-gray-50">
    <ProjectsPage client:only="react" />
  </div>
</Layout>

2. ProjectsPage.tsx - Main Component

Responsibilities:

• Fetch projects from the API on mount
• Manage loading/error/empty states
• Handle search/filter logic
• Coordinate modal states for create/edit/delete
• Pass data to ProjectCard components

Key State:

- projects: Project[]
- filteredProjects: Project[]
- isLoading: boolean
- searchQuery: string
- showCreateModal: boolean
- editingProject: Project | null
- deletingProjectId: string | null
- userAddress: string | null

3. ProjectCard.tsx - Project Display Component

Props:

interface ProjectCardProps {
  project: Project;
  isOwner: boolean;
  onEdit: () => void;
  onDelete: () => void;
}

Visual Elements:

• Project icon/avatar (code symbol)
• Project name (prominent heading)
• Description (truncated with line-clamp-3)
• Owner address (formatted)
• Edit/Delete buttons (only visible to owner)
• Hover effects for interactivity

Design Pattern: Similar to badge cards with a white background, subtle border, and shadow on hover

4. CreateProjectModal.tsx - Project Creation

Features:

• Form with name (max 100 chars) and description (max 500 chars)
• Client-side validation
• Loading state during submission
• Error handling and display
• Success callback to refresh project list

API Integration:

POST /api/projects
Body: { name: string, description: string }

5. EditProjectModal.tsx - Project Editing

Features:

• Pre-populated form with existing project data
• Same validation as create modal
• Owner verification before submission
• Success callback to refresh project list

API Integration:

PATCH /api/projects/:id
Body: { name: string, description: string }

6. DeleteConfirmationDialog.tsx - Deletion Confirmation

Features:

• Warning message: "Are you sure? This cannot be undone."
• Display project name for confirmation
• Loading state during deletion
• Success callback to remove project from list

API Integration:

DELETE /api/projects/:id

Page Layout

Visual Structure

┌─────────────────────────────────────────────────────────────┐
│  Header: "The Guild Genesis"         [Sign In] [Wallet]     │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  Projects                                                    │
│                                                              │
│  Showcase your work. Projects can be created by anyone      │
│  and are managed by their owners.                           │
│                                                              │
│  [Search projects...]              [+ Create Project]       │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                 │
│  │ Project  │  │ Project  │  │ Project  │                 │
│  │  Card    │  │  Card    │  │  Card    │                 │
│  │          │  │          │  │          │                 │
│  └──────────┘  └──────────┘  └──────────┘                 │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                 │
│  │ Project  │  │ Project  │  │ Project  │                 │
│  │  Card    │  │  Card    │  │  Card    │                 │
│  └──────────┘  └──────────┘  └──────────┘                 │
└─────────────────────────────────────────────────────────────┘

Layout Details

• Max width: max-w-7xl mx-auto
• Padding: px-4 sm:px-6 lg:px-8 py-8
• Grid: grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6
• Search bar: Full width on mobile, flex-1 on desktop with create button beside it

Key Features

1. Search Functionality

• Real-time filtering by project name or description
• Case-insensitive matching
• Updates the grid dynamically
• Shows "No projects found" message when search returns no results

const handleSearch = (query: string) => {
  setSearchQuery(query);
  const filtered = projects.filter(project => 
    project.name.toLowerCase().includes(query.toLowerCase()) ||
    project.description.toLowerCase().includes(query.toLowerCase())
  );
  setFilteredProjects(filtered);
};

2. Authentication Integration

• Check wallet connection using window.ethereum
• Store user address in state
• Show the create button only for authenticated users
• Show edit/delete buttons only for project owners
• Owner verification: project.ownerAddress === userAddress

3. Responsive Design

Grid Breakpoints:

• Mobile (< 768px): 1 column
• Tablet (768px - 1023px): 2 columns
• Desktop (≥ 1024px): 3 columns

Card Design:

• Consistent minimum height
• Truncated descriptions (line-clamp-3)
• Stack buttons vertically on small screens

4. State Management

Loading State:

• Show loading spinner while fetching projects
• Disable interactions during creation/editing/deletion

Empty State:

• Show a friendly message when no projects exist
• Provide "Create Project" button
• Differentiate between "no projects" and "no search results"

Error Handling:

• Display error messages in a red banner
• Catch and handle API errors gracefully
• Provide user-friendly error messages

Navigation Integration

Add to AppSidebar.tsx or navigation component:

{ 
  name: 'Projects', 
  path: '/projects', 
  icon: CodeIcon // or similar code/folder icon
}

Design System

Colours (Tailwind Classes)

Background: bg-gray-50
Cards: bg-white with border-grey-200
Primary Button: bg-black text-white hover: bg-grey-800
Text Primary: text-grey-900
Text Secondary: text-grey-600
Text Muted: text-grey-500
Icon Background: bg-blue-100
Icon Colour: text-blue-600
Edit Action: text-blue-600 hover:bg-blue-50
Delete Action: text-red-600 hover:bg-red-50

Typography

Page Title: text-4xl font-bold
Card Title: text-xl font-semibold
Description: text-sm
Owner Info: text-xs

Spacing

Container Padding: px-4 sm:px-6 lg:px-8 py-8
Card Padding: p-6
Grid Gap: gap-6
Button Gap: gap-2

User Flows

Create Project Flow

1. User clicks the "Create Project" button
2. Modal opens with an empty form
3. User enters project name and description
4. Client-side validation checks (required fields, character limits)
5. Submit → POST request to /api/projects
6. On success: close modal, refresh project list, show success message
7. On error: display error message, keep modal open

Edit Project Flow

1. Owner clicks the "Edit" button on their project card
2. Modal opens with form pre-populated with existing data
3. User modifies fields
4. Validation checks on submit
5. Submit → PATCH request to /api/projects/:id
6. On success: close modal, refresh project list
7. On error: display error message, keep modal open

Delete Project Flow

1. Owner clicks the "Delete" button on their project card
2. Confirmation dialogue appears: "Are you sure you want to delete [Project Name]? This cannot be undone."
3. User clicks "Confirm"
4. Submit → DELETE request to /api/projects/:id
5. On success: remove project from grid with animation, close dialogue
6. On error: display error message

Browse/Search Flow

1. User lands on /projects page
2. All projects load in the grid (newest first)
3. User types in the search box
4. Grid updates in real-time to show matching projects
5. User clicks on the project to view details (future enhancement)

Implementation Phases

Phase 1: Basic Structure

• Create projects.astro page
• Create ProjectsPage.tsx with basic layout
• Add Projects route to navigation
• Verify page renders with Layout component

Phase 2: Display Projects

• Implement ProjectCard.tsx component
• Add API fetch logic in ProjectsPage
• Display projects in a responsive grid
• Add loading, empty, and error states

Phase 3: Create Functionality

• Implement CreateProjectModal.tsx
• Add form validation
• Connect to POST /api/projects
• Handle success and error cases

Phase 4: Edit Functionality

• Implement EditProjectModal.tsx
• Pre-populate form with project data
• Connect to PATCH /api/projects/:id
• Refresh list on successful edit

Phase 5: Delete Functionality

• Implement DeleteConfirmationDialog.tsx
• Connect to DELETE /api/projects/:id
• Remove project from list on success

Phase 6: Search & Polish

• Implement search/filter functionality
• Add animations and transitions
• Test authentication and ownership checks
• Responsive design testing
• Accessibility audit (keyboard navigation, ARIA labels)

Accessibility Considerations

• Semantic HTML elements (main, section, article)
• ARIA labels for icon buttons and form inputs
• Keyboard navigation support (Tab, Enter, Escape)
• Focus management in modals (trap focus, return focus on close)
• Colour contrast compliance (WCAG AA)
• Screen reader-friendly error messages
• Loading state announcements

Testing Checklist

• Page loads without errors
• Projects fetch and display correctly
• Search for projects accurately
• Create modal validates and submits
• Edit modal pre-populates and updates
• Delete confirmation works and removes the project
• Owner-only actions are hidden from non-owners
• Responsive design works on mobile, tablet, and desktop
• Loading states display properly
• Empty state shows when no projects exist
• Error states display user-friendly messages
• Wallet connection integrates correctly
• Navigation link works

Success Metrics

✅ Users can create projects with a name and description
✅ Project owners can edit their projects
✅ Project owners can delete their projects
✅ All projects display in a clean, organised grid
✅ Search functionality works smoothly
✅ Design matches existing Guild Genesis aesthetics
✅ No console errors or performance issues
✅ Responsive on all screen sizes
✅ Accessible via keyboard and screen readers

---

[joelamouche]

Great work on specing this out!
Also don't forget to put all api calls into tanstack query hooks (as already implemented for profiles). This wil help with api status ux feedback