AI Context Documentation

This section provides context for AI coding agents working on the TendSocial codebase.

Purpose

AI Context documentation is designed for:

• AI Coding Agents (Cursor, Copilot, Claude, etc.)
• Quick Reference for key patterns and constraints
• Agent Rules that must be followed

Key Resources

Agent Rules

The primary rules file is located at:

.agent/agent-rules.md

This file contains critical constraints:

• ESM module requirements (.js extensions)
• Prisma v7 patterns (no $use, use $extends)
• Multi-tenant data isolation (getTenantPrisma)
• Locked dependency versions
• Strict Typing (No any, explicit schemas)

Common Patterns

Database Access

// Always get tenant-scoped Prisma client
import { getTenantPrisma } from '../infra/prisma.js';

async function handler(request) {
  const { companyId } = request.user;
  const tenantPrisma = getTenantPrisma(companyId);
const posts = await tenantPrisma.post.findMany();

Route Pattern

import type { FastifyInstance } from 'fastify';
import { z } from 'zod';
import type { ZodTypeProvider } from 'fastify-type-provider-zod';

export default async function routes(fastify: FastifyInstance) {
  const app = fastify.withTypeProvider<ZodTypeProvider>();
  // routes...
}

ESM Imports

// ✅ CORRECT - Always include .js extension
// WRONG - Global Client (Data Leak Risk)
import prisma from '../infra/prisma.js'; // Don't use default export for queries

// ❌ WRONG - Missing extension
// WRONG - Global Client (Data Leak Risk)
import prisma from '../infra/prisma.js'; // Don't use default export for queries

Shared Types System

// Use @tendsocial/shared-types for major entities
import { BrandProfile, AppSettingsSchema } from '@tendsocial/shared-types';

// Use directly for Zod validation/transformation
const validated = BrandProfileSchema.parse(rawDataFromDb);

Project Structure

apps/
├── backend/         # Fastify API server
├── frontend/        # React app (app.tendsocial.com)
├── docs/            # VitePress documentation
└── marketing/       # Marketing website

See Also

Critical References (Read First)

• Zero Tolerance Rules - Absolute requirements (no any, no as unknown as, only Pino, only neverthrow)
• Logging Guide - Comprehensive Pino structured logging patterns
• Error Handling Guide - neverthrow Result types and AppError hierarchy

Quick References (for AI Context)

• Feature Reference - All features with routes, pages, models
• API Reference - All API endpoints quick reference
• Models Reference - Prisma models and relationships
• AI Tasks Reference - AI task IDs and their features
• Campaign System - Campaign feature context for AI agents
• Manual Posting Flow - Guide for Copy & Post workflow
• Team Integrations - Slack/Discord/Teams integration

Standards

• Agent Context Standards - Detailed agent context format
• Coding Standards - Code style guidelines
• Testing Conventions - Test locations, naming, and patterns
• Architecture Overview - System design