TECH-DEBT: CLAUDE-SONNET-4.5

PROJECT_SYNC_GUIDE.MD

---

CLAUDE IS HELPFUL, BUT BE MINDFUL OF JUST ROUGE CODE

THIS PROJECTS FEATURE WAS SOMETHING I PROBABLY SHOULD HAVE JUST ADDED IT MYSELF.

WHAT STARTED AS A QUESTION ABOUT ADDING PROJECT LOGGING IN FRONTEND CODE. RESULTED IN A FULL SCAFFOLD, DELETION, AND ADDITION THAT WILL TAKE ME LONGER TO CLEAN UP THAN IT WOULD HAVE IF I READ A DOC AND WROTE THE CODE MYSELF

---

THIS CREATES DEBT.

TRUSTING GENERATED CODE OR PERHAPS GENERATED ANYTHING WITHOUT REVIEWING AND UNDERSTANDING WHAT IT DOES OR HOW IT FUNCTIONS WILL ALWAYS CREATE AN ISSUE SOMEWHERE IN YOUR BUILD PROCESS.

DEBT.

---

MANAGE YOUR DEBT.

COST

bash

Total usage est:       4 Premium requests
 Total duration (API):  2m 39.5s
 Total duration (wall): 1h 18m 42.0s
 Total code changes:    258 lines added, 18 lines removed
 Usage by model:
     claude-sonnet-4.5    750.2k input, 9.2k output, 0 cache read, 0 cache write (Est. 4 Premium requests)

CONNECT:GH ISSUE DOCS.31 ---

GitHub Projects Integration Guide

Overview

The GitHub Projects integration automatically fetches and tracks GitHub Projects (v2) using the GitHub API. Projects are synced on-demand via API endpoints.

How It Works

Architecture

code

GitHub GraphQL API → github_client.py → log_service.py → API Endpoints
                          ↓
              Fetches Projects (org/user)
                          ↓
              Stores in memory (projects dict)
                          ↓
              Exposes via /api/projects

API Endpoints

1. Sync Projects (Admin Only)

POST /api/projects/sync

Fetches projects from GitHub and syncs them to the local cache.

Request:

json

{
  "owner": "unparty-app",
  "type": "org",
  "installation_id": 12345
}

Parameters:

owner - GitHub organization or username

type - Either "org" or "user" (default: "org")

installation_id - GitHub App installation ID

Response:

json

{
  "status": "success",
  "synced": 5,
  "owner": "unparty-app",
  "type": "org"
}

Example:

bash

curl -X POST http://localhost:8000/api/projects/sync \
  -H "Authorization: Bearer YOUR_CLERK_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "unparty-app",
    "type": "org",
    "installation_id": 12345
  }'

2. Get Projects

GET /api/projects?state=open

Retrieve all tracked projects with optional filtering.

Query Parameters:

state (optional) - Filter by state: "open" or "closed"

Response:

json

{
  "projects": [
    {
      "id": "PVT_kwDOABC123",
      "title": "theunpartybuilder Roadmap",
      "number": 1,
      "url": "https://github.com/orgs/unparty-app/projects/1",
      "owner": "unparty-app",
      "state": "open",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-11-22T06:00:00Z",
      "last_synced": "2025-11-22T06:19:00Z"
    }
  ],
  "total": 1
}

Example:

bash

# Get all projects
curl http://localhost:8000/api/projects

# Get only open projects
curl http://localhost:8000/api/projects?state=open

Code Usage

In Python (backend)

python

from backend.handlers import github_client
from backend.log_service import log_service

# Fetch organization projects
projects = github_client.get_organization_projects(
    org="unparty-app",
    installation_id=12345
)

# Sync to log service
log_service.sync_projects(projects)

# Get tracked projects
all_projects = log_service.get_projects()
open_projects = log_service.get_projects(state="open")

# Get specific project
project = log_service.get_project("PVT_kwDOABC123")

GitHub App Permissions

To use this feature, your GitHub App needs these permissions:

Organization permissions:

Projects: Read-only (minimum)

Repository permissions:

(none required for projects)

Setup Steps

1. Update GitHub App Permissions:

Go to: https://github.com/settings/apps/your-app-name

Under "Organization permissions"

Set "Projects" to "Read-only" or "Read & Write"

Save changes

2. Reinstall App:

Users must accept the new permissions

Or visit the installation page to update

3. Sync Projects:

Call /api/projects/sync with admin token

Projects are stored in memory

Re-sync periodically to update

Data Storage

Projects are stored in-memory in log_service.projects:

✅ Fast access

✅ No database needed

⚠️ Lost on restart (re-sync needed)

To persist projects across restarts, consider:

Syncing on startup

Adding database storage

Setting up periodic sync (cron/scheduler)

Future Enhancements

[ ] Auto-sync on installation webhook

[ ] Periodic background sync

[ ] Project webhook events

[ ] Database persistence

[ ] Project items/cards tracking

[ ] Dashboard UI for projects

Troubleshooting

"Failed to fetch projects"

Verify GitHub App has Projects permission

Check installation_id is correct

Ensure token has proper scopes

Empty projects list

Organization might not have Projects v2

User might not have public projects

Run sync endpoint first to populate

Authentication errors

/api/projects/sync requires admin Clerk token

/api/projects allows optional auth

---

Created: 2025-11-22 Part of: theunpartybuilder ecosystem