rs, request body, or special headers beyond standard HTTP conventions. Session authentication is typically handled via cookies or framework-managed session tokens in Next.js App Router environments.

Headers

Header	Required	Description
Accept	Optional	application/json (recommended)
Cookie / Session Token	Yes	Valid admin session cookie or authentication token

Query Parameters

None.

Request Body

None.

Example Request Structure

GET /api/admin/analytics HTTP/1.1
Host: api.codcompass.com
Accept: application/json
Cookie: session=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response Format

Success Response (200 OK)

Returns a JSON object containing placeholder traffic metrics, real database counts, and an implementation note.

Field	Type	Description
totalViews	number	Placeholder (0). Real tracking pending.
totalClicks	number	Placeholder (0). Real tracking pending.
avgTimeOnPage	string	Placeholder ("0s").
bounceRate	string	Placeholder ("0%").
dailyViews	array	Empty array. Will contain time-series view data.
topArticles	array	Empty array. Will contain most-viewed article objects.
trafficSources	array	Empty array. Will contain referrer/source breakdown.
totalArticles	number	Count of articles with status: 'PUBLISHED'.
totalCategories	number	Total number of categories in the system.
totalUsers	number	Total registered users.
activeSubscriptions	number	Users with subscriptionStatus: 'ACTIVE'.
note	string	Implementation status message regarding traffic tracking.

Example Success Response

{
  "totalViews": 0,
  "totalClicks": 0,
  "avgTimeOnPage": "0s",
  "bounceRate": "0%",
  "dailyViews": [],
  "topArticles": [],
  "trafficSources": [],
  "totalArticles": 142,
  "totalCategories": 18,
  "totalUsers": 3850,
  "activeSubscriptions": 210,
  "note": "Page view tracking not implemented yet. Integrate Google Analytics, Plausible, or add a views table for real traffic data."
}

Error Responses

Status Code	Description	Response Body
403 Forbidden	Missing admin session or insufficient role	{"error": "Forbidden"}
500 Internal Server Error	Database connection failure, Prisma query error, or auth service outage	{"error": "Internal server error"}

Usage Example

Below is a practical curl command demonstrating how to call the endpoint. Replace the placeholder cookie with a valid admin session token in your environment.

curl -X GET "https://api.codcompass.com/api/admin/analytics" \
  -H "Accept: application/json" \
  -H "Cookie: session=your_valid_admin_session_token"

In a frontend framework (e.g., React/Next.js), you would typically fetch this data inside a server component or a protected client route:

// Example: Next.js Server Component
const analytics = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/admin/analytics`, {
  cache: 'no-store', // Aligns with force-dynamic behavior
  headers: {
    Cookie: cookies().toString(),
  },
}).then(res => res.json());

Common Pitfalls

1. Expecting Real Traffic Data Immediately
   The endpoint returns zeros and empty arrays for all traffic-related fields (totalViews, dailyViews, topArticles, etc.). This is intentional. Frontend dashboards should gracefully handle empty arrays and zero values, and display the note field to inform administrators that traffic tracking is pending integration.

2. Caching Conflicts
   Although the route exports dynamic = 'force-dynamic', Next.js may still cache responses if the calling layer overrides fetch options (e.g., cache: 'force-cache' or revalidate: 3600). Always ensure fetch calls to this endpoint use cache: 'no-store' or equivalent dynamic rendering flags to avoid stale admin metrics.

3. Authentication Mismatch
   The endpoint metadata may list authentication as "Public," but the implementation strictly checks for an admin role via auth(). Requests from unauthenticated users or standard users will receive 403 Forbidden. Ensure your API client or framework passes the session cookie correctly, and verify that the user's role payload includes role: 'ADMIN'.

Related Endpoints

This analytics endpoint is typically used alongside other administrative and content-management routes that share the same authentication layer and database schema:

• /api/articles – Retrieve, create, or update published knowledge base articles. Useful for cross-referencing totalArticles counts.
• /api/admin/users – Manage user accounts and subscription statuses. Complements totalUsers and activeSubscriptions metrics.
• /api/categories – List or modify content categories. Aligns with totalCategories for content taxonomy reporting.

These routes follow the same Next.js App Router conventions, Prisma data access patterns, and session-based role validation, making them straightforward to integrate into unified admin dashboards or automated reporting pipelines.