agency-frontend

Build and maintain the Social Media Agency Next.js frontend with dashboard UI, content calendar, analytics, and responsive design. Use when creating pages, components, layouts, forms, or frontend conf

SKILL.md

GitHub

Social Media Agency Next.js Frontend

Tech Stack

{
  "dependencies": {
    "next": "^14.2",
    "react": "^18.3",
    "react-dom": "^18.3",
    "@radix-ui/react-dialog": "^1.1",
    "@radix-ui/react-dropdown-menu": "^2.1",
    "@radix-ui/react-tabs": "^1.1",
    "@radix-ui/react-select": "^2.1",
    "class-variance-authority": "^0.7",
    "clsx": "^2.1",
    "tailwind-merge": "^2.5",
    "lucide-react": "^0.460",
    "recharts": "^2.13",
    "zustand": "^4.5",
    "@tanstack/react-query": "^5.60",
    "@dnd-kit/core": "^6.1",
    "@dnd-kit/sortable": "^8.0",
    "react-hook-form": "^7.53",
    "@hookform/resolvers": "^3.9",
    "zod": "^3.23",
    "sonner": "^1.7",
    "date-fns": "^3.6"
  }
}

API Client

Typed client wrapping fetch with automatic auth headers.

// lib/api.ts
const API_BASE = process.env.NEXT_PUBLIC_API_URL || "http://localhost:8001";

class ApiError extends Error {
  constructor(public status: number, message: string) {
    super(message);
  }
}

async function request<T>(path: string, options?: RequestInit): Promise<T> {
  const token = typeof window !== "undefined"
    ? localStorage.getItem("token")
    : null;

  const res = await fetch(`${API_BASE}${path}`, {
    ...options,
    headers: {
      "Content-Type": "application/json",
      ...(token ? { Authorization: `Bearer ${token}` } : {}),
      ...options?.headers,
    },
  });

  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new ApiError(res.status, body.detail || "Request failed");
  }
  return res.json();
}

export const api = {
  health: () => request<{ status: string }>("/api/v1/health"),

  // Auth
  login: (email: string, password: string) =>
    request<{ access_token: string; role: string }>("/api/v1/auth/login", {
      method: "POST", body: JSON.stringify({ email, password }),
    }),
  signup: (data: SignupRequest) =>
    request<{ access_token: string }>("/api/v1/auth/signup", {
      method: "POST", body: JSON.stringify(data),
    }),

  // Clients
  getClients: (page = 1) =>
    request<ClientListResponse>(`/api/v1/clients?page=${page}`),
  getClient: (id: string) =>
    request<ClientResponse>(`/api/v1/clients/${id}`),
  createClient: (data: ClientCreateRequest) =>
    request<ClientResponse>("/api/v1/clients", {
      method: "POST", body: JSON.stringify(data),
    }),

  // Campaigns
  getCampaigns: (clientId?: string) =>
    request<CampaignListResponse>(`/api/v1/campaigns${clientId ? `?client_id=${clientId}` : ""}`),
  createCampaign: (data: CampaignCreateRequest) =>
    request<CampaignResponse>("/api/v1/campaigns", {
      method: "POST", body: JSON.stringify(data),
    }),

  // Content
  getContent: (params?: ContentQueryParams) =>
    request<ContentListResponse>(`/api/v1/content?${new URLSearchParams(params as any)}`),
  createContent: (data: ContentCreateRequest) =>
    request<ContentResponse>("/api/v1/content", {
      method: "POST", body: JSON.stringify(data),
    }),
  generateContent: (data: ContentGenerateRequest) =>
    request<ContentGenerateResponse>("/api/v1/content/generate", {
      method: "POST", body: JSON.stringify(data),
    }),

  // Calendar
  getCalendarEvents: (start: string, end: string) =>
    request<CalendarEvent[]>(`/api/v1/calendar?start=${start}&end=${end}`),
  rescheduleContent: (contentId: string, scheduledAt: string) =>
    request<ContentResponse>(`/api/v1/calendar/${contentId}/reschedule`, {
      method: "PATCH", body: JSON.stringify({ scheduled_at: scheduledAt }),
    }),

  // Approvals
  getPendingApprovals: () =>
    request<ApprovalListResponse>("/api/v1/approvals?status=pending"),
  approveContent: (contentId: string) =>
    request<ApprovalResponse>(`/api/v1/approvals/${contentId}/approve`, { method: "POST" }),
  rejectContent: (contentId: string, feedback: string) =>
    request<ApprovalResponse>(`/api/v1/approvals/${contentId}/reject`, {
      method: "POST", body: JSON.stringify({ feedback }),
    }),

  // Analytics
  getDashboardStats: () =>
    request<DashboardStats>("/api/v1/analytics/dashboard"),
  getClientAnalytics: (clientId: string, period: string) =>
    request<AnalyticsResponse>(`/api/v1/analytics/clients/${clientId}?period=${period}`),

  // Assets
  uploadAsset: (formData: FormData) =>
    request<AssetResponse>("/api/v1/assets", {
      method: "POST",
      body: formData,
      headers: {},
    }),

  // Billing
  getSubscription: () =>
    request<Subscription>("/api/v1/billing/subscription"),
  createCheckout: (planId: string) =>
    request<{ url: string }>("/api/v1/billing/checkout", {
      method: "POST", body: JSON.stringify({ plan_id: planId }),
    }),

  // Email
  setupOrgEmail: () =>
    request<{ inbox_id: string; email: string }>("/api/v1/organizations/email/setup", {
      method: "POST",
    }),
  getEmailStatus: () =>
    request<{ configured: boolean; email: string | null }>("/api/v1/organizations/email/status"),
};

Page Template

"use client";

import { useEffect, useState } from "react";
import { toast } from "sonner";
import { api } from "@/lib/api";

export default function FeaturePage() {
  const [data, setData] = useState<DataType[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    api.getData()
      .then(setData)
      .catch((err) => toast.error(err.message))
      .finally(() => setLoading(false));
  }, []);

  if (loading) return <PageSkeleton />;

  return (
    <div className="space-y-6">
      <div className="flex items-center justify-between">
        <h1 className="text-2xl font-bold text-slate-900">Feature</h1>
      </div>
      {/* Content */}
    </div>
  );
}

Dashboard Layout

// app/(dashboard)/layout.tsx
"use client";
import { useState } from "react";
import { Sidebar } from "@/components/layout/sidebar";
import { Topbar } from "@/components/layout/topbar";
import { MobileNav } from "@/components/layout/mobile-nav";

export default function DashboardLayout({ children }: { children: React.ReactNode }) {
  const [sidebarOpen, setSidebarOpen] = useState(false);

  return (
    <div className="min-h-screen bg-gradient-to-br from-slate-50 to-indigo-50/30">
      <Sidebar className="hidden lg:fixed lg:inset-y-0 lg:flex lg:w-64" />
      <MobileNav open={sidebarOpen} onClose={() => setSidebarOpen(false)} />
      <div className="lg:pl-64">
        <Topbar onMenuClick={() => setSidebarOpen(true)} />
        <main className="p-4 sm:p-6 lg:p-8">{children}</main>
      </div>
    </div>
  );
}

KPI Card

// components/analytics/kpi-card.tsx
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { TrendingUp, TrendingDown } from "lucide-react";

interface KPICardProps {
  label: string;
  value: string;
  changePct: number;
  icon: React.ReactNode;
  loading?: boolean;
}

export function KPICard({ label, value, changePct, icon, loading }: KPICardProps) {
  if (loading) {
    return (
      <Card>
        <CardContent className="p-6">
          <div className="h-4 w-24 animate-pulse rounded bg-slate-200" />
          <div className="mt-3 h-8 w-32 animate-pulse rounded bg-slate-200" />
        </CardContent>
      </Card>
    );
  }

  const isPositive = changePct >= 0;

  return (
    <Card>
      <CardHeader className="flex flex-row items-center justify-between pb-2">
        <CardTitle className="text-sm font-medium text-muted-foreground">{label}</CardTitle>
        {icon}
      </CardHeader>
      <CardContent>
        <div className="text-2xl font-bold">{value}</div>
        <div className={`mt-1 flex items-center gap-1 text-sm ${
          isPositive ? "text-emerald-600" : "text-red-600"
        }`}>
          {isPositive ? <TrendingUp className="h-4 w-4" /> : <TrendingDown className="h-4 w-4" />}
          {isPositive ? "+" : ""}{changePct.toFixed(1)}%
        </div>
      </CardContent>
    </Card>
  );
}

Content Editor with AI

// components/content/content-editor.tsx
"use client";

import { useState } from "react";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { toast } from "sonner";
import { Sparkles } from "lucide-react";
import { api } from "@/lib/api";

const schema = z.object({
  body: z.string().min(1, "Content body is required"),
  platform: z.string().min(1, "Select a platform"),
  hashtags: z.string().optional(),
  scheduled_at: z.string().optional(),
});

type FormData = z.infer<typeof schema>;

export function ContentEditor({ clientId, onSuccess }: { clientId: string; onSuccess: () => void }) {
  const [generating, setGenerating] = useState(false);
  const {
    register,
    handleSubmit,
    setValue,
    watch,
    formState: { errors, isSubmitting },
  } = useForm<FormData>({ resolver: zodResolver(schema) });

  async function handleGenerate() {
    setGenerating(true);
    try {
      const result = await api.generateContent({
        client_id: clientId,
        platform: watch("platform"),
        topic: watch("body") || "general engagement post",
        tone: "professional",
        content_type: "post",
      });
      setValue("body", result.body);
      if (result.hashtags) setValue("hashtags", result.hashtags.join(" "));
      toast.success("Content generated!");
    } catch (err: any) {
      toast.error(err.message);
    } finally {
      setGenerating(false);
    }
  }

  async function onSubmit(data: FormData) {
    try {
      await api.createContent({
        client_id: clientId,
        platform: data.platform,
        body: data.body,
        hashtags: data.hashtags?.split(/\s+/).filter(Boolean) || [],
        scheduled_at: data.scheduled_at || undefined,
      });
      toast.success("Content created!");
      onSuccess();
    } catch (err: any) {
      toast.error(err.message);
    }
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)} className="space-y-6">
      <div>
        <label className="block text-sm font-medium text-slate-700 mb-1">Platform</label>
        <select
          {...register("platform")}
          className="w-full rounded-lg border border-slate-300 px-4 py-2.5 text-slate-900 focus:border-indigo-500 focus:ring-1 focus:ring-indigo-500 outline-none"
        >
          <option value="">Select platform...</option>
          <option value="instagram">Instagram</option>
          <option value="facebook">Facebook</option>
          <option value="twitter">Twitter / X</option>
          <option value="linkedin">LinkedIn</option>
          <option value="tiktok">TikTok</option>
        </select>
        {errors.platform && <p className="mt-1 text-xs text-red-500">{errors.platform.message}</p>}
      </div>

      <div>
        <div className="flex items-center justify-between mb-1">
          <label className="block text-sm font-medium text-slate-700">Content</label>
          <button
            type="button"
            onClick={handleGenerate}
            disabled={generating}
            className="flex items-center gap-1 text-xs text-indigo-600 hover:text-indigo-500"
          >
            <Sparkles className="h-3 w-3" />
            {generating ? "Generating..." : "AI Generate"}
          </button>
        </div>
        <textarea
          {...register("body")}
          rows={5}
          className="w-full rounded-lg border border-slate-300 px-4 py-2.5 text-slate-900 placeholder-slate-400 focus:border-indigo-500 focus:ring-1 focus:ring-indigo-500 outline-none resize-none"
          placeholder="Write your post content or use AI to generate..."
        />
        {errors.body && <p className="mt-1 text-xs text-red-500">{errors.body.message}</p>}
      </div>

      <div>
        <label className="block text-sm font-medium text-slate-700 mb-1">Hashtags</label>
        <input
          {...register("hashtags")}
          className="w-full rounded-lg border border-slate-300 px-4 py-2.5 text-slate-900 placeholder-slate-400 focus:border-indigo-500 focus:ring-1 focus:ring-indigo-500 outline-none"
          placeholder="#socialmedia #marketing #growth"
        />
      </div>

      <button
        type="submit"
        disabled={isSubmitting}
        className="w-full rounded-lg bg-indigo-600 px-6 py-2.5 font-semibold text-white hover:bg-indigo-500 disabled:opacity-50 transition-colors"
      >
        {isSubmitting ? "Creating..." : "Create Content"}
      </button>
    </form>
  );
}

Calendar View (Drag & Drop)

// components/calendar/content-calendar.tsx
"use client";

import { DndContext, DragEndEvent } from "@dnd-kit/core";
import { toast } from "sonner";
import { api } from "@/lib/api";

interface CalendarEvent {
  id: string;
  title: string;
  platform: string;
  scheduledAt: string;
  status: string;
  clientName: string;
}

export function ContentCalendar({ events }: { events: CalendarEvent[] }) {
  async function handleDragEnd(event: DragEndEvent) {
    const { active, over } = event;
    if (!over || active.id === over.id) return;

    try {
      await api.rescheduleContent(active.id as string, over.id as string);
      toast.success("Content rescheduled");
    } catch (err: any) {
      toast.error(err.message);
    }
  }

  return (
    <DndContext onDragEnd={handleDragEnd}>
      <div className="grid grid-cols-7 gap-px bg-slate-200 rounded-xl overflow-hidden">
        {/* Calendar grid with draggable content cards */}
      </div>
    </DndContext>
  );
}

Loading Skeleton

function PageSkeleton() {
  return (
    <div className="space-y-4">
      <div className="h-8 w-48 animate-pulse rounded-lg bg-slate-200" />
      <div className="grid grid-cols-1 md:grid-cols-4 gap-4">
        {[...Array(4)].map((_, i) => (
          <div key={i} className="h-28 animate-pulse rounded-xl bg-slate-200" />
        ))}
      </div>
      <div className="h-64 animate-pulse rounded-xl bg-slate-200" />
    </div>
  );
}

Error Boundary

// app/(dashboard)/error.tsx
"use client";
export default function DashboardError({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <div className="flex min-h-[400px] flex-col items-center justify-center gap-4">
      <h2 className="text-xl font-semibold text-slate-900">Something went wrong</h2>
      <p className="text-slate-500">{error.message}</p>
      <button onClick={reset} className="rounded-lg bg-indigo-600 px-4 py-2 text-white hover:bg-indigo-500">
        Try again
      </button>
    </div>
  );
}

Platform Color Coding

// lib/platform-colors.ts
export const PLATFORM_COLORS: Record<string, { bg: string; text: string; border: string }> = {
  instagram: { bg: "bg-pink-50", text: "text-pink-700", border: "border-pink-200" },
  facebook: { bg: "bg-blue-50", text: "text-blue-700", border: "border-blue-200" },
  twitter: { bg: "bg-sky-50", text: "text-sky-700", border: "border-sky-200" },
  linkedin: { bg: "bg-indigo-50", text: "text-indigo-700", border: "border-indigo-200" },
  tiktok: { bg: "bg-slate-50", text: "text-slate-700", border: "border-slate-200" },
};

Key Rules

  1. Never hardcode backend URLs — use NEXT_PUBLIC_API_URL
  2. Always use the api client — never raw fetch in components
  3. Always provide loading skeletons — never blank screens
  4. Always define TypeScript interfaces for API responses
  5. Dashboard uses light theme — slate/indigo palette
  6. Toast notifications via sonner — never alert()
  7. Icons from lucide-react only
  8. Mobile-first — design for 375px, scale up with sm:, md:, lg:
  9. Sidebar collapses on screens < 1024px
  10. Drag-and-drop via @dnd-kit for calendar and content ordering
  11. Color-code content by platform — use the PLATFORM_COLORS map