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.

Documentation-First Workflow

Agents must treat repository documentation as the source of truth. Conversation history is secondary and may be incomplete, stale, or contradictory.

Before making any substantial code change, agents must read the relevant docs first. At minimum, inspect:

• AGENTS.md
• docs/LLM_DEVELOPMENT_WORKFLOW.md
• docs/PRODUCT.md when product behavior, UX, or user workflow may change
• docs/ARCHITECTURE.md when structure, module boundaries, routing, data flow, or integration points may change
• docs/CONVENTIONS.md when adding or modifying code patterns
• docs/DECISIONS.md before revisiting architecture or product decisions
• the active docs/tasks/TASK-*.md file when one exists

If one of these files does not exist yet, do not invent broad behavior from chat history. State what is missing and proceed only with the narrowest safe interpretation of the current task.

For non-trivial work, follow this sequence:

1. Read the relevant docs and existing code.
2. Restate the task in a short summary.
3. Identify backend impact, frontend impact, data impact, and documentation impact.
4. List files likely to change.
5. Surface ambiguities or risky assumptions.
6. Propose a minimal implementation plan.
7. Implement only the approved or clearly requested scope.
8. Validate with the relevant commands before finishing when possible.

Do not use a long chat thread as the durable memory for the project. Durable decisions, conventions, and task requirements belong in repository docs.

Pair Working Mode

• Work as a pair with the repository owner, not as an isolated implementer.
• Before substantial changes, read the relevant docs first, then restate the task briefly and inspect the existing code.
• 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 (net10.0) API using FastEndpoints, EF Core (PostgreSQL), ASP.NET Identity, and modular bounded contexts for workflow data.
• frontend/: Vue 3 + Vite + Vuetify + Pinia + Vue Router + Tailwind CSS SPA.
• .github/workflows/: build/deploy pipelines for backend (Azure Web App) and frontend (Azure Static Web Apps).

Local Runbook

Backend

• Prereqs: .NET 10 SDK, Docker, PostgreSQL container.
• Start database:
  • cd backend
  • ./scripts/start-infrastructure.sh
• Run API:
  • dotnet run --project Socialize.Api.csproj (from backend/)
• Local API URL:
  • http://localhost:5000
• Swagger/OpenAPI UI in dev:
  • /api

Frontend

• Prereqs: Node/npm.
• Runtime configuration:
  • frontend app config is loaded from .env.development and .env.production
  • frontend/src/config.js is the single frontend source of truth for runtime env access
• Commands:
  • cd frontend && npm install
  • npm run dev
  • npm run build
• Local dev server:
  • http://localhost:5173

Backend Architecture

Composition Root

• Entry point: backend/Program.cs.
• Registers:
  • Web services/auth (backend/DependencyInjection.cs)
  • Infrastructure services (backend/Infrastructure/DependencyInjection.cs)
  • Modules: Identity, Workspaces, Clients, Projects, ContentItems, Assets, Comments, Approvals, Notifications.
• 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, Workspaces, Clients, Projects, ContentItems, Assets, Comments, Approvals, Notifications.
• 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.
• Role-gated frontend routes currently use Administrator and Manager checks for settings access.

Current Domain Modules

• Identity: authentication, refresh tokens, email verification, password reset, social login.
• Workspaces: workspace membership, workspace settings, access scoping.
• Clients: client records and primary contacts tied to workspaces.
• Projects: project pipeline and client/project relationships.
• ContentItems: reviewable content records tied to clients/projects.
• Assets: linked asset metadata and revision history.
• Comments: discussion threads on reviewable work.
• Approvals: review decisions and workflow state transitions.
• Notifications: activity feed and unread workflow notifications.

Frontend Architecture

Bootstrap

• frontend/src/main.js wires Vue app + Pinia + Vuetify + Router + i18n + Google OAuth + Toasts.
• frontend/src/config.js is the app-facing runtime configuration module. Do not scatter import.meta.env reads across the app.

Routing

• Defined in frontend/src/router/router.js.
• Route guards enforce:
  • meta.requiresAuth
  • meta.notAuthenticated
  • optional meta.roles
• Primary authenticated app routes live under /app/*.

State Management

• Pinia stores:
  • authStore: token lifecycle + refresh concurrency guard.
  • workspaceStore: active workspace context.
  • clientsStore: client list and creation flows.
  • projectsStore: project list and creation flows.
  • contentItemsStore and contentItemDetailStore: content item listing/detail flows.
  • reviewQueueStore: pending review work.
  • notificationsStore: workflow notifications.
  • userProfileStore: current user profile and account edits.

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 (backend/Modules/Identity/*, frontend/src/views/auth/*).
• Workspace-scoped operations and role checks (backend/Modules/Workspaces/*, frontend/src/stores/workspaceStore.js, frontend/src/router/router.js).
• Client and project workflow (backend/Modules/Clients/*, backend/Modules/Projects/*, frontend/src/views/app/ClientsView.vue, frontend/src/views/app/ProjectsView.vue).
• Content review lifecycle (backend/Modules/ContentItems/*, backend/Modules/Assets/*, backend/Modules/Comments/*, backend/Modules/Approvals/*, frontend/src/views/app/ContentItemsView.vue, frontend/src/views/app/ContentItemDetailView.vue, frontend/src/views/app/ReviewQueueView.vue).
• Notifications and workflow awareness (backend/Modules/Notifications/*, frontend/src/stores/notificationsStore.js).

Task-Driven Development With Agents

Use docs/tasks/TASK-*.md files as LLM-friendly implementation tickets. A task file should be self-contained enough for a fresh agent to understand the desired change without relying on a long conversation.

A good task file defines:

• objective and product context
• scope and out of scope
• backend requirements, API contract, validation, data, authorization
• frontend requirements, route/screen, components, state, API integration, UX states
• files likely involved
• acceptance criteria
• validation plan
• risks and open questions

Features are fullstack by default unless the task explicitly says otherwise. Do not assume a feature is backend-only. For user-facing work, define both backend and frontend behavior before implementation.

When an adjacent issue is discovered outside the task scope, do not fix it opportunistically. Report it as a suggested backlog item or add it to docs/BACKLOG.md if explicitly asked.

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. Keep frontend runtime configuration centralized in frontend/src/config.js and .env.*; do not introduce ad hoc env fallbacks.
6. Preserve workspace scoping and route-role checks when editing app flows.
7. Do not commit secrets. Existing appsettings and env files include sensitive-looking values; treat them as legacy and avoid propagating.
8. For non-trivial features, prefer a docs/tasks/TASK-*.md file before implementation.
9. Treat frontend behavior as part of the feature definition: route, components, Pinia store usage, API integration, loading/error/success states, and navigation must be explicit or derived from existing patterns.
10. If requirements conflict with repository docs, stop and surface the conflict instead of silently choosing one.

Validation Checklist Before Finishing

• Backend:
  • cd backend && dotnet build Socialize.Api.csproj
  • run affected endpoint flows if change touches handlers/auth/workspace scoping/data writes
• Frontend:
  • cd frontend && npm run build
  • validate affected route/store interactions in browser when UI behavior changed
• If migrations were changed:
  • ensure module context name/output directory remain consistent with backend/scripts/add-migration.sh.

Notes / Known Sharp Edges

• Frontend config should come through .env.development / .env.production and frontend/src/config.js; avoid direct import.meta.env reads in feature code.
• Backend development now runs on HTTP locally (http://localhost:5000), while HTTPS redirection stays enabled outside development.
• frontend/.env.development is currently checked in and points VITE_API_URL to http://192.168.1.2:5000; verify whether changes should target localhost or the LAN host before editing.
• Some style/formatting is inconsistent across JS/Vue/C# files; minimize churn to touched lines.