Retrieve a paginated list of projects belonging to the authenticated user’s tenant. Supports filtering by status, searching by name or description, and sorting by recent activity, name, or status.

• All endpoints require a valid JWT access token.
• Projects are automatically scoped to the authenticated user’s tenant — a user can only see their own projects.
• ARCHIVED projects are excluded from the default list. To see archived projects, the client must explicitly filter by status=ARCHIVED.
• The progress field is included in each project item. It is null when the project status is not BUILDING, and an integer 0-100 when the status is BUILDING.

Limitation (MVP): Progress tracking is a stub — the backend always returns 0 for projects in BUILDING status.

sequenceDiagram
    actor User

    User->>+FE: opens Projects screen

    FE->>+BE: GET /api/v1/projects?page=0&size=20&sort=recent <br> Authorization: Bearer {accessToken}

    BE->>BE: validate JWT access token
    alt access token invalid or missing
        BE-->>FE: 401 Unauthorized <br> ErrorResponse
    end

    BE->>DB: query projects by tenant_id <br> apply filters, search, sort, pagination

    BE->>-FE: 200 OK <br> ProjectListResponse

    FE->>-User: display project list

    User->>+FE: applies filter / search / sort

    FE->>+BE: GET /api/v1/projects?status=LIVE&search=bakery&sort=name&page=0&size=20 <br> Authorization: Bearer {accessToken}

    BE->>DB: query projects with filters

    BE->>-FE: 200 OK <br> ProjectListResponse

    FE->>-User: display filtered project list

GET /api/v1/projects (query parameters):

200 OK ProjectListResponse:

{
  "data": [
    {
      "id": 1,
      "name": "Wildwood Bakery",
      "description": "Online ordering for a neighborhood bakery",
      "status": "LIVE",
      "url": "wildwood-bakery.talkide.app",
      "accent": "oklch(0.78 0.15 70)",
      "techStack": "Vue + Spring Boot",
      "progress": null,
      "previewUrl": "http://localhost:5201",
      "createdAt": "2026-04-20T10:00:00Z",
      "updatedAt": "2026-04-29T14:30:00Z"
    },
    {
      "id": 2,
      "name": "Pet Tracker",
      "description": "GPS tracking app for pet owners",
      "status": "BUILDING",
      "url": "pet-tracker.talkide.app",
      "accent": "oklch(0.72 0.12 160)",
      "techStack": "React + Node.js",
      "progress": 0,
      "previewUrl": "http://localhost:5202",
      "createdAt": "2026-04-25T08:00:00Z",
      "updatedAt": "2026-04-29T12:00:00Z"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 2,
  "totalPages": 1
}

401 Unauthorized (missing or invalid access token) ErrorResponse:

{
  "status": 401,
  "code": "AUTHENTICATION_FAILED",
  "message": "Access token is missing or invalid"
}

Frontend

Validations

No form inputs — this is a read-only listing. Filter/search/sort parameters are controlled via UI components.

Backend

Validations

Test Cases