Skip to content

Frontend migration foundation: Read-only React Contexts + Server Action mutations across all services with NextJS page structure #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 12 commits into
base: main
Choose a base branch
from
Draft

Frontend migration foundation: Read-only React Contexts + Server Action mutations across all services with NextJS page structure #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
d475257
Initial plan
Copilot Feb 4, 2026
1d66989
Add React contexts and page structure for frontend migration
Copilot Feb 4, 2026
b893cbb
Add comprehensive frontend migration documentation
Copilot Feb 4, 2026
557d450
Add architecture comparison diagram
Copilot Feb 4, 2026
f4a81c4
Refactor contexts to use Immutable.js and integrate with server actions
Copilot Feb 4, 2026
2b36bdf
wip: dream context patterning
mlynam Feb 6, 2026
0e99ea0
feat: add context pattern
mlynam Feb 7, 2026
2017b6b
Refactor contexts to match DreamContext pattern
Copilot Feb 7, 2026
4f2804a
Refactor contexts to be read-only with server action mutations
Copilot Feb 7, 2026
fbf31e1
Refactor dream services: one export per file, FormData for saveYearVi…
Copilot Feb 7, 2026
e7488b2
Apply form action pattern to all services (weeks, connects, scoring, …
Copilot Feb 7, 2026
76ddc18
Fix withAuth usage: use as function wrapper not inside body
Copilot Feb 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
327 changes: 327 additions & 0 deletions ARCHITECTURE_DIAGRAM.md
View file
Open in desktop
Copy link
Copy Markdown
Member

@mlynam mlynam Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's cleanup this go-forward architecture:

  1. Mutations occur primarily via forms -> form actions (services) using formdata and zod. Secondary mutations which do not use formdata are: reordering and toggling.
  2. Contexts provide data to read from but they do not provide mutations. Mutations are triggered by service calls only and should force a revalidation that cascades through the context.

Copy link
Copy Markdown
Contributor Author

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Refactored architecture to match this pattern (4f2804a):

✅ Read-only contexts - All 6 contexts now only provide data via immutable Lists, no mutation methods
✅ Form actions with FormData - Created saveDreamFormAction and deleteDreamFormAction using Zod + FormData, compatible with useActionState
✅ Non-form mutations - Created reorderDreams(dreams[]) and updateYearVision(vision) with simple signatures
✅ Revalidation cascade - All server actions call revalidatePath() to refresh context data

Example:

// Context is read-only
const { dreams } = useDreams();

// Form mutations use useActionState
const [state, action] = useActionState(saveDreamFormAction, null);
<form action={action}>...</form>

// Non-form mutations are simple calls
await reorderDreams(newOrder);

Original file line number Diff line number Diff line change
@@ -0,0 +1,327 @@
# Dreamspace Architecture: Legacy vs New

## Legacy Architecture (src/)

```
┌─────────────────────────────────────────────────────────────┐
│ Browser (Client Only) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌─────────────────────┐ │
│ │ React Router │────────▶│ Page Components │ │
│ └──────────────┘ └──────────┬──────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ AppContext │ │
│ │ (Redux-like) │ │
│ │ │ │
│ │ • Dreams │ │
│ │ • Goals │ │
│ │ • User │ │
│ │ • Connects │ │
│ │ • Scoring │ │
│ │ • Team │ │
│ │ │ │
│ │ 30+ Actions │ │
│ │ 315 LOC Reducer │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ Custom Hooks │ │
│ │ (32 hooks) │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ Services Layer │ │
│ │ (21 services) │ │
│ └──────────┬──────────┘ │
└──────────────────────────────────────┼──────────────────────┘
│
│ HTTP/REST
│
┌──────────▼──────────┐
│ Azure Functions │
│ (50+ functions) │
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ Cosmos DB │
└─────────────────────┘
```

## New Architecture (apps/web/)

```
┌─────────────────────────────────────────────────────────────┐
│ Server (NextJS) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌─────────────────────┐ │
│ │ App Router │────────▶│ Server Components │ │
│ │ │ │ (Pages - RSC) │ │
│ └──────────────┘ └──────────┬──────────┘ │
│ │ │
│ │ fetch data │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ Server Actions │ │
│ │ (70+ actions) │ │
│ │ │ │
│ │ • users/ │ │
│ │ • dreams/ │ │
│ │ • weeks/ │ │
│ │ • teams/ │ │
│ │ • scoring/ │ │
│ │ • connects/ │ │
│ │ │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ Database Client │ │
│ │ (@dreamspace/db) │ │
│ └──────────┬──────────┘ │
└──────────────────────────────────────┼──────────────────────┘
│
┌──────────▼──────────┐
│ Cosmos DB │
└─────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ Browser (Client) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Client Components (Interactive) │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Dream │ │ Goal │ │ User │ │ │
│ │ │ Context │ │ Context │ │ Context │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Connect │ │ Team │ │ Scoring │ │ │
│ │ │ Context │ │ Context │ │ Context │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ │ │
│ │ (Contexts only for UI state) │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```

## Key Differences

| Aspect | Legacy | New |
|--------|--------|-----|
| **Rendering** | Client-side only | Server + Client |
| **State** | Centralized Redux | Distributed Contexts |
| **Data Flow** | Client → API → DB | Server → DB → Client |
| **Routing** | React Router (client) | NextJS (server) |
| **API Layer** | Azure Functions | Server Actions |
| **Bundle Size** | Large (all client) | Small (server-first) |
| **SEO** | Poor | Excellent |
| **Performance** | Slower initial load | Faster initial load |
| **Complexity** | 30+ actions, 1 reducer | 6 contexts, focused |

## Data Flow Comparison

### Legacy: Client-Heavy
```
User Action
↓
React Component
↓
Dispatch Action → Reducer → Context Update
↓
useEffect triggered
↓
Service Layer (client)
↓
HTTP Request → Azure Function
↓
Cosmos DB
↓
Response → State Update
↓
localStorage sync
↓
Component Re-render
```

### New: Server-First
```
Page Load
↓
Server Component
↓
Server Action (direct DB access)
↓
Cosmos DB
↓
Render HTML
↓
Send to Client

User Interaction
↓
Client Component
↓
Server Action (mutation)
↓
Cosmos DB
↓
revalidatePath
↓
Server Component re-fetches
↓
Render updated HTML
```

## Component Architecture

### Legacy Three-Layer Pattern
```
┌─────────────────────────────────┐
│ DashboardLayout.jsx │ ◀─── Orchestrator
│ - State management │
│ - Side effects │
│ - Event handlers │
└──────────┬──────────────────────┘
│
┌──────▼─────────┐
│ useDashboard │ ◀─── Business Logic Hook
│ Hook │
│ - Data fetch │
│ - Calculations │
└──────┬─────────┘
│
┌──────▼─────────┐
│ Presentational │ ◀─── Pure UI Components
│ Components │
│ - No state │
│ - Props only │
└────────────────┘
```

### New Server-First Pattern
```
┌─────────────────────────────────┐
│ page.tsx (Server) │ ◀─── Server Component
│ - Auth check │
│ - Data fetching │
│ - Render │
└──────────┬──────────────────────┘
│
│ Pass data as props
│
┌──────▼─────────┐
│ Client │ ◀─── Client Component
│ Components │
│ - Interactive │
│ - Use contexts │
│ - Event handlers│
└──────┬─────────┘
│
│ Mutations
│
┌──────▼─────────┐
│ Server Actions │ ◀─── Server-side logic
│ - Validation │
│ - DB updates │
│ - Revalidation │
└────────────────┘
```

## File Organization

### Legacy
```
src/
├── pages/
│ ├── Dashboard.jsx (thin wrapper)
│ └── dashboard/
│ ├── DashboardLayout.jsx (orchestrator)
│ ├── DashboardHeader.jsx
│ ├── WeekGoalsWidget.jsx
│ └── week-goals/
│ ├── index.js
│ ├── GoalItem.jsx
│ └── AddGoalForm.jsx
├── context/
│ ├── AppContext.jsx (global state)
│ └── AuthContext.jsx
├── state/
│ ├── appReducer.js (315 LOC)
│ └── actionTypes.js
├── hooks/
│ ├── useDashboard.js
│ ├── useDreamActions.js
│ └── ... (32 hooks)
└── services/
├── apiClient.js
├── dreamService.js
└── ... (21 services)
```

### New
```
apps/web/
├── app/
│ ├── dashboard/
│ │ └── page.tsx (server component)
│ ├── dream-book/
│ │ └── page.tsx
│ └── layout.tsx (with providers)
├── components/
│ ├── dashboard/
│ │ ├── DashboardHeader.tsx
│ │ ├── WeekGoalsWidget.tsx
│ │ └── DashboardDreamCard.tsx
│ └── shared/
│ └── Navigation.tsx
├── lib/
│ └── contexts/ (6 focused contexts)
│ ├── DreamContext.tsx
│ ├── GoalContext.tsx
│ ├── UserContext.tsx
│ ├── ConnectContext.tsx
│ ├── TeamContext.tsx
│ ├── ScoringContext.tsx
│ └── AppProviders.tsx
└── services/ (70+ server actions)
├── dreams/
├── users/
├── weeks/
└── ...
```

## Migration Benefits

1. **Performance**
- ⚡ Faster initial page load (server rendering)
- 📦 Smaller client bundle (no Redux, less JS)
- 🎯 Automatic code splitting (NextJS)
- 🔄 Parallel data fetching

2. **Developer Experience**
- 📝 Type-safe throughout (TypeScript)
- 🎨 Clearer separation of concerns
- 🧪 Easier to test (isolated contexts)
- 📚 Better documentation

3. **Maintainability**
- 🔍 Easier to understand (smaller contexts)
- 🔧 Easier to modify (focused responsibilities)
- 🚀 Easier to deploy (NextJS built-in)
- 📊 Better error tracking

4. **User Experience**
- 🌐 SEO-friendly (server rendering)
- ♿ More accessible (progressive enhancement)
- 📱 Better mobile performance
- 🔒 More secure (server-side auth)

---

**Migration Status**: Phase 1 Complete ✅
**Next Phase**: Component Stubbing (80+ components)
Loading