social-media/AGENTS.md

AGENTS.md

Purpose

This document is a working guide for coding agents in this repository. It captures the current architecture, conventions, and safe execution workflow for making reliable changes.

Pair Working Mode

• Work as a pair with the repository owner, not as an isolated implementer.
• Before substantial changes, restate the task briefly and inspect the existing code or docs first.
• Surface assumptions, tradeoffs, and blockers early instead of silently picking risky directions.
• Prefer small, reviewable increments when the product direction is still being shaped.
• When requirements are exploratory, help turn them into concrete workflows, domain language, and next implementation steps.
• Do not rewrite broad areas of the codebase without clear justification from the current task.
• Preserve user changes in the worktree and treat uncommitted files as active collaboration unless told otherwise.
• When creating commits, use the Conventional Commits format, for example docs: update product planning.

Repository Layout

• backend/: ASP.NET Core (net9.0) API using FastEndpoints, EF Core (PostgreSQL), Stripe, Azure Blob Storage, and ASP.NET Identity.
• frontend/: Vue 3 + Vite + Vuetify + Pinia + Vue Router + Tailwind CSS SPA.
• .github/workflows/: deploy pipelines for backend (Azure Web App) and frontend (Azure Static Web Apps).

Local Runbook

Backend

• Prereqs: .NET 9 SDK, Docker, PostgreSQL container.
• Start database:
  • cd backend
  • ./scripts/start-infrastructure.sh
• Run API:
  • dotnet run (from backend/)
• Swagger/OpenAPI UI in dev:
  • /api

Frontend

• Prereqs: Node/npm, local HTTPS cert files expected by Vite:
  • frontend/localhost-key.pem
  • frontend/localhost.pem
• Commands:
  • cd frontend && npm install
  • npm run dev
  • npm run build

Backend Architecture

Composition Root

• Entry point: backend/Program.cs.
• Registers:
  • Web services/auth (backend/DependencyInjection.cs)
  • Infrastructure services (backend/Infrastructure/DependencyInjection.cs)
  • Modules: Identity, Creators, Contents, Memberships, Tipping, Messaging.
• Each module has:
  • Add{Module}Module(...) to register DbContext/services.
  • Use{Module}ModuleAsync() to auto-run migrations at startup.

API Style

• FastEndpoints-based handlers.
• Pattern: request/response records + optional FluentValidation validator + handler class.
• Tagging via Options(o => o.WithTags("...")).
• File upload handlers call AllowFileUploads().

Data Boundaries

• Separate DbContext per module:
  • Identity, Creators, Contents, Memberships, Tipping, Messaging.
• Migrations are module-scoped under each Modules/*/Migrations folder.

Auth/Security

• JWT is generated manually in Infrastructure/Security/GenerateJwtToken.cs.
• Refresh-token flow is implemented in Identity handlers (/api/users/login, /api/users/refresh).
• User claim helpers live in Infrastructure/Security/ClaimsPrincipalExtensions.cs.

Payments/Stripe

• Tip checkout: Infrastructure/Payments/Stripe/Services/StripeTipProcessor.cs.
• Membership checkout: Infrastructure/Payments/Stripe/Services/MembershipPaymentProcessor.cs.
• Webhook endpoint: Modules/Memberships/Handlers/StripeWebhookEndpoint.cs.
• Creator onboarding/status/revoke Stripe:
  • /api/stripe/connect
  • /api/stripe/check-status
  • DELETE /api/stripe

Blob Storage

• IBlobStorage implemented by AzureBlobStorage.
• Upload size/type checks are enforced there (10 MB max + content-type validation).

Frontend Architecture

Bootstrap

• frontend/src/main.js wires Vue app + Pinia + Vuetify + Router + i18n + Google OAuth + Toasts.

Routing

• Defined in frontend/src/router/router.js.
• Route guards enforce:
  • meta.requiresAuth
  • meta.notAuthenticated
• Creator public route convention: /@:creator.

State Management

• Pinia stores:
  • authStore: token lifecycle + refresh concurrency guard.
  • userProfileStore: current user profile and account edits.
  • creatorProfileStore: creator-owned profile actions.
  • brandingStore: creator page branding fetched from slug route param.

API Client

• Axios client in frontend/src/plugins/api.js.
• Injects bearer token, proactively refreshes near expiry, retries once on 401.

High-Value Domains

• Identity and social login (Modules/Identity/*, frontend/src/views/auth/*).
• Creator public profile and management (Modules/Creators/*, frontend/src/views/creators/*, frontend/src/views/profile/*).
• Monetization:
  • Tips (Modules/Tipping/*, creator donation UI)
  • Memberships (Modules/Memberships/*, Stripe webhook orchestration)
• Content albums/photo upload (Modules/Contents/*).
• Messaging thread/replies (Modules/Messaging/*).

Agent Working Rules For This Repo

1. Keep module boundaries intact. Do not couple DbContexts across modules.
2. When adding endpoints, follow existing FastEndpoints pattern with validator + explicit route + tag.
3. If schema changes are needed, generate migration in the matching module only.
4. Preserve token refresh behavior in frontend client/store; avoid introducing parallel refresh races.
5. For file uploads, enforce content-type/size limits and reuse blob path conventions.
6. Keep creator route contract stable (/@slug) because frontend and backend both depend on it.
7. Do not commit secrets. Existing appsettings include sensitive-looking values; treat as legacy and avoid propagating.

Validation Checklist Before Finishing

• Backend:
  • cd backend && dotnet build
  • run affected endpoint flows if change touches handlers/auth/payments/storage
• Frontend:
  • cd frontend && npm run build
  • validate affected route/store interactions in browser
• If migrations were changed:
  • ensure module context name/output directory remain consistent with backend/scripts/add-migration.sh.

Notes / Known Sharp Edges

• Frontend expects VITE_API_URL in API plugin; src/config.js uses VITE_APP_API_URL naming. Keep env usage consistent when editing.
• GetReceivedTips currently resolves tipper with tip.CreatorId instead of tip.CreatedBy; verify intent before refactoring.
• Some style/formatting is inconsistent across JS/Vue/C# files; minimize churn to touched lines.