---
name: project-portfolio-v2
description: "Architecture decisions and build plan for APEX Portfolio v2.0 — SSO-ready, Google Sheets backend, instructor dashboard"
metadata: 
  node_type: memory
  type: project
  originSessionId: 79d3087b-93bd-42dd-8f8b-a4ea5fbdfd1c
---

v2.0 of the APEX Portfolio system. Building with SSO in mind using an auth stub, so when SSO is approved only one function needs to change.

**Why:** Move from localStorage to a real backend, enable instructor dashboards, heat maps, artifact repository, cross-device sync, and Google Drive folder creation on first login.

**Target launch:** Start of 2026–27 school year (August 2026).

## Key Architecture Decisions

**Auth stub pattern:** Single `getCurrentUser()` function returns hardcoded test identity now. Swap for real Google OAuth when SSO approved. Supports `localStorage` override for testing both roles (student-associate / instructor).

**Backend:** One Google Spreadsheet (permanent, not per-year). `school_year` and `course_id` columns on all rows. Pre-aggregated `stats` sheet for instructor dashboard so it doesn't scan full tables. Apps Script web app as API layer — same pattern as BPRM and beta test form.

**Portfolio identity (Option C):** One portfolio per student-associate, career-spanning. Standards 1, 2, 3, 5 accumulate across all courses. Standard 4 is pathway-specific (tagged to course). Instructor dashboard filters to their course/cohort. A student in multiple APEX courses simultaneously shows in all relevant instructors' views.

**Folder structure:** v2 lives in a separate `v2/` subfolder during development. When ready, replaces v1 files entirely. v1 stays untouched until launch.

**Roster timing:** Rosters tab in Spreadsheet exists from day one but stays empty until August. Instructor dashboard shows graceful empty states. Manual CSV import when rosters are available; auto-sync when SSO lands.

## Spreadsheet Schema

Sheet tabs:
- `users` — id, name, email, role, strand, instructor_id, drive_folder_id, created_at
- `artifacts` — id, user_id, standard, artifact_id, title, link, reflection, done, opted_into_repo, course_id, school_year, updated_at
- `checkins` — id, user_id, date, project, worked, next, blockers, artifact_std, artifact_id, course_id, school_year, created_at
- `playbook_progress` — id, user_id, playbook, project_name, state_json, course_id, school_year, updated_at
- `rosters` — instructor_id, student_id, course_id, school_year
- `repository` — moderated opt-in anonymized artifact submissions
- `stats` — pre-aggregated instructor dashboard data (updated on every artifact save)

## Features by Phase

**Phase 1 — Foundation**
- Auth stub + getCurrentUser()
- Apps Script backend + all Sheets tabs
- Data sync layer (Sheets primary, localStorage as offline cache)
- All existing pages updated to use backend
- Reference implementation: Portfolio home + Standard 1

**Phase 2 — Enhanced Portfolio**
- Drag-and-drop UI on artifact cards (URL paste fallback; actual upload needs SSO)
- Shareable read-only portfolio link
- Artifact opt-in toggle for repository

**Phase 3 — Instructor Dashboard**
- Roster management UI (manual entry for now)
- Heat map per Standard (artifact cards colored by completion % across class)
- Individual student-associate progress view

**Phase 4 — Artifact Repository**
- Browse by Standard + artifact type
- Moderation queue (Russ approves before anything goes public)
- Submission flow from artifact cards

**Phase 5 — SSO Activation (when approved)**
- Swap getCurrentUser() for Google OAuth
- Enable Drive folder creation on first login
- Enable actual file upload on drag-and-drop
- Roster auto-sync if Google Workspace allows

## Features Deferred

- Notifications (v2.X, not v2.0)
- Gamification: must be minimal and opt-IN if ever added — see [[feedback-gamification]]

## Drive Folder Structure (SSO-dependent)

Created on first login if drive_folder_id is null in users sheet:
```
My Drive/
└── APEX Portfolio/
    ├── S1 — Servant Leadership/
    │   └── (one subfolder per artifact card)
    ├── S2 — Beyond GPA/
    ├── S3 — Career Exploration/
    ├── S4 — Technical Skills/
    └── S5 — Professional Skills/
```
Root folder ID saved to users sheet. Drag-and-drop uploads to matching artifact subfolder.

**How to apply:** When building any v2 feature, check this schema first. All data reads/writes go through the Apps Script API. Keep getCurrentUser() calls consistent — never hardcode user identity elsewhere.