Frontend Architecture

The plugzero-analytics repository is a high-performance Next.js 15 application. We use the App Router to manage our complex research dashboard, separate from our marketing presence.

📁 Repository Structure

We follow a modular “Domain-First” structure to ensure that as we add new intelligence engines (like SEO or social listening), the codebase remains clean and decoupled.

1. The Route Groups (src/app)

We use Next.js Route Groups to apply different layouts and middleware logic without adding segments to the URL.

• (marketing): Contains the landing pages, pricing, and blog. These use a light-weight navigation and footer.
• (dashboard): The heart of the platform. It includes 15+ specialized zones:
  • /analysis: Where the “Analytics Workbench” and AI engines live.
  • /data-collection: Interface for CSV/Excel uploads and ingestion.
  • /surveys: The survey builder and response dashboard.
  • /seo: The SEO Intelligence and Site Audit dashboard.
  • /media-intelligence: Social media monitoring and brand listening.
  • /team: Workspace management, role assignments, and invitations.
• auth/: Shared login, registration, and 2FA flows.
• survey/: The public-facing survey response portal (isolated from the main app for speed).

2. Strategic Components (src/components)

Components are organized by the Domain they serve. We avoid a giant shared folder.

• ui/: Atomic, Radix-based primitives (Buttons, Dialogs, Toasts).
• analytics/: High-performance chart wrappers (Recharts/D3) and math tables.
• data-collection/: Specialized components for file-drop zones and ingestion progress trackers.
• surveys/: Componentry for the visual survey-flow builder.
• seo-intelligence/: Visualization components for site audit scores and keyword trends.

3. The API Protocol (src/lib/api)

We maintain a strict 1-to-1 mapping between our Django models and our TypeScript API modules. This ensures total predictability when calling the backend.

• analysis.ts: Handlers for math calculations and AI summaries.
• surveys.ts: Handlers for survey logic and responses.
• project.ts: The core “CRUD” operations for research projects.
• seo.ts: Handlers for triggering and fetching site audits.
• base-api-fetcher.ts: The core fetch wrapper that handles JWT injection and error normalization.

🏗️ Core Architectural Patterns

We rely on three pillars to maintain a professional developer experience:

The RSC-First Rule

Every page in the dashboard starts as a React Server Component (RSC).

1. The layout fetches the Active Project context on the server.
2. The metadata (Titles, SEO tags) are generated on the server.
3. We only ship “Interactive Boundaries” ('use client') for specific widgets like charts or drag-and-drop builders.

Server Actions for Mutations

We avoid useEffect for data writing. Every state-changing action (Creating a team, deleting a file) is a Server Action found in src/app/actions.ts or domain-specific action files. This reduces the need for complex client-side state management.

Zustand & Context for Global State

• Context: Used for “Heavy” state like the current Project Context, making it available to all nested research dashboards.
• Zustand: Used for ephemeral UI state, such as whether the research sidebar is collapsed or the current theme settings.

⚙️ Development Environment

• Framework: Next.js 15 (App Router)
• Styling: Tailwind CSS + Shadcn UI
• State: React Context + Zustand
• Charts: Recharts & Nivo
• Data Fetching: Server Components + Custom Fetcher in lib/