social-media/docs/archive/PLAN.md

PLAN

Historical planning snapshot. This document reflects the early product-pivot plan and is not the source of truth for the current implementation state.

Purpose

This document defines the build plan to close the gap between the current codebase and the target product described in SOCIALIZE.md.

The current repository is a dead Hutopy codebase. The target product, temporarily named Socialize, is a workflow application for social media content review, revision, approval, and readiness for publication.

This is a full product pivot, not a gradual feature expansion.

Goal

Build a product that becomes the system of workflow for:

• internal content review
• provider collaboration
• client approval
• version tracking
• audit trail
• notification-driven progress
• publication readiness handoff

The first version should solve the approval pain cleanly before deeper integrations or scheduling features are added.

Gap Summary

Current Codebase

The current repository contains:

• backend modular structure with FastEndpoints and Entity Framework Core
• authentication and infrastructure foundations
• file storage patterns
• frontend Vue application shell
• legacy business modules centered on creators, tipping, memberships, and creator-facing experiences

Target Product

The target product needs:

• workspace and client management
• provider and internal team collaboration
• content item lifecycle management
• asset and revision tracking
• comments and approval workflow
• workflow events and notifications
• client-facing review portal
• Google Drive-centered asset ownership
• billing readiness for a future Software as a Service offering

Core Gap

The codebase has technical scaffolding that can be reused, but the business domain is largely wrong for the target product.

The main gap is not infrastructure. The main gap is domain shape, frontend surface, and workflow behavior.

Build Principles

1. Reuse technical foundations when they help, but do not keep old business concepts for convenience.
2. Keep the modular backend structure.
3. Prefer clean domain language from day one over transitional naming.
4. Build around Google Drive ownership first, not direct-upload-first assumptions.
5. Deliver one vertical workflow before broad integrations.
6. Remove legacy Hutopy product concepts early to reduce semantic drag.
7. Keep changes reviewable and validate each phase before widening scope.

Keep, Replace, Remove

Keep

• ASP.NET Core backend shell
• FastEndpoints setup
• modular registration pattern
• Entity Framework Core with per-module context where useful
• infrastructure wiring
• authentication foundation if it can be adapted cleanly
• payment infrastructure patterns and Stripe integration capability for future billing
• blob or file-handling patterns that still apply
• Vue, Vite, Pinia, router, and API client shell
• deployment workflows if still useful for the new product

Replace

• domain module set
• route design
• data model
• frontend information architecture
• user flows
• branding and product language

Remove

• creator domain concepts
• creator public profile features
• creator monetization flows
• Hutopy naming across code and frontend copy
• dead UI components and stores tied only to the old product

Retire And Rebuild

• old tipping business flows
• old membership business flows
• creator-specific Stripe onboarding flows
• payment routes and models that are tightly coupled to the dead Hutopy business model

Keep the underlying payment capability, but rebuild the business-facing billing model around the new product when pricing and subscription design are ready.

Target Product Scope For Version 1

Version 1 should own this workflow:

1. Internal team creates a content item.
2. Assets are linked from Google Drive.
3. Publication message and metadata are attached.
4. Internal reviewer or provider receives a request.
5. Comments and revisions happen in one place.
6. Client receives a review request.
7. Client approves, rejects, or requests changes.
8. Item becomes ready for publishing handoff.

Not version 1:

• full scheduling engine
• full social publishing
• advanced third-party synchronization
• analytics suite
• full digital asset management platform
• full creative production tooling
• customer billing and subscription management user flows

Target Backend Module Map

Recommended backend modules:

• Identity
  • users, authentication, internal roles
• Workspaces
  • agencies or operating teams
• Clients
  • brands, creators, businesses served by a workspace
• Providers
  • external production partners
• Projects
  • grouped bodies of work for a client, which may later contain campaign concepts if needed
• ContentItems
  • reviewable units with metadata, copy, due dates, and status
• Assets
  • asset references, Google Drive linkage, versions, previews
• Approvals
  • review requests, approvers, decisions, status transitions
• Comments
  • threads, replies, resolution state, contextual discussion
• Notifications
  • workflow events, reminders, delivery preferences

Possible later modules:

• Campaigns
• Calendars
• Integrations
• Publishing
• Analytics
• Billing

Target Frontend Surface

Recommended frontend areas:

• authentication
• workspace switcher or workspace context
• client list
• project list
• review queue dashboard
• content item detail page
• revision and comment timeline
• approval status panel
• notification center
• external client review portal

Later frontend areas:

• calendar view
• integration settings
• publishing handoff dashboard
• workflow analytics

Proposed Data Backbone

Content Item

A content item should carry:

• title
• publication message
• notes
• project
• client
• creator or brand context where relevant
• publication targets
• publication dates by network when relevant
• due date
• current status
• current active revision set

Asset

An asset should carry:

• asset type
• source type
• Google Drive file reference
• preview metadata
• current version
• version history

Approval Request

An approval request should carry:

• target content item
• requested reviewers
• stage type
• sent at
• due at
• decision state
• decision history

Notification Event

A notification event should carry:

• event type
• triggered by
• target entity
• recipients
• delivery status
• timestamps

Execution Strategy

Phase 0: Freeze Product Direction

Deliverables:

• validated worksheet in English
• optional French mirror of the worksheet
• agreed module map
• agreed version 1 scope and anti-scope

Exit criteria:

• no ambiguity about the first workflow to build
• no unresolved disagreement about Google Drive ownership

Phase 1: Remove Legacy Product Surface

Goals:

• reduce confusion from Hutopy concepts
• make the codebase ready for the new domain

Work:

• remove or retire legacy frontend views tied to creators, tipping, and memberships
• remove legacy backend modules that are clearly dead
• rename product-facing strings, assets, and configuration references
• identify infrastructure pieces that stay
• preserve Stripe and payment infrastructure that can support future Software as a Service billing
• identify backend modules that should be replaced instead of adapted

Exit criteria:

• codebase no longer communicates the old product direction
• remaining code clearly supports reuse or is queued for replacement

Phase 2: Establish New Domain Skeleton

Goals:

• introduce the new product vocabulary into code
• prepare clean module boundaries

Work:

• create new backend modules
• define initial entities and contexts
• wire modules in Program.cs
• define route namespaces and tags
• create frontend route skeleton for the new product
• define new stores for auth, workspace context, review queue, and content items

Exit criteria:

• application compiles with the new module map in place
• legacy domain is no longer the center of the app

Phase 3: Build The First Vertical Slice

Vertical slice:

• create content item
• link Google Drive asset
• add publication message and publication target data
• request internal review
• comment on item
• request changes
• upload or register a new revision
• request client review
• approve from client portal
• mark ready to publish

Backend work:

• commands and queries for content item creation and retrieval
• asset linkage and versioning
• comment creation and retrieval
• approval request and decision endpoints
• status transition logic
• workflow event emission

Frontend work:

• content item creation flow
• content item detail view
• comments panel
• approval action UI
• status timeline
• simple client review page

Exit criteria:

• one item can move end-to-end from draft to approved
• all actions are traceable in one place

Phase 4: Add Notification Backbone

Goals:

• make workflow movement visible without manual follow-up

Work:

• define notification event types
• trigger events on comments, revisions, requests, and decisions
• add email notifications
• add in-app notification center or lightweight feed
• add reminder jobs for pending reviews

Exit criteria:

• users are informed when workflow events occur
• delayed approvals can be followed without manual chasing

Phase 5: Harden Version 1 For Real Usage

Goals:

• make the workflow usable for the first real client

Work:

• permissions and role hardening
• validation and error handling
• audit trail review
• filtering and dashboard improvements
• comment resolution
• required approver logic if needed
• publication dates by network support
• quality pass on mobile review experience

Exit criteria:

• the first client can run a real approval cycle in the product

Phase 6: Evaluate Phase 2 Expansion

Candidates:

• calendar visibility
• Google Drive sync improvements
• Canva linkage
• MailChimp approval path
• scheduler handoff integrations
• billing and subscription management for the Software as a Service offer

Rule:

Only start these after version 1 workflow is demonstrably useful.

Immediate Technical Tasks

Recommended next implementation tasks:

1. Rename the product and remove visible Hutopy branding.
2. Inventory which backend modules are deleted versus replaced.
3. Define the new backend module directories and initial project structure.
4. Replace the frontend router with the new application surface.
5. Model ContentItem, Asset, AssetVersion, ApprovalRequest, ApprovalDecision, CommentThread, and NotificationEvent.
6. Implement the first vertical slice end to end.

Risks

• scope creep into scheduling and publishing too early
• forcing the new domain into old creator-centric structures
• under-designing workflow status and revision semantics
• overbuilding integrations before the core workflow is proven
• making external review too heavy for clients

Validation Checklist

Before claiming version 1 readiness:

• a workspace can manage at least one client
• a content item can include publication message and publication targets
• assets can be linked from Google Drive
• internal review can request changes
• client review can approve or reject
• status history is visible
• notification events are triggered
• the latest approved state is clear

Working Note

This plan should be updated as soon as the first implementation decisions are made, especially:

• exact module names
• exact database boundaries
• whether Providers stands alone or is modeled as a participant role
• whether notifications are their own module or an infrastructure concern