Add comprehensive frontend architecture specification for Cogito web platform

[Copilot]

Problem statement requested a production-ready frontend architecture proposal for Cogito, requiring answers to 10 backend specification questions before implementation could proceed. Cogito currently operates as CLI-only Python application with no web interface.

Deliverables (4,692 lines across 7 documents)

Core Specifications:

• FRONTEND_ARCHITECTURE.md (1,366 lines) - Complete technical specification with technology stack justifications, modular feature architecture, data access patterns, security/auth design, testing strategies
• BACKEND_DETAILS_RESPONSE.md (626 lines) - Definitive answers to all 10 questions: protocols (REST + WebSocket), authentication (OAuth2 + JWT), 6 core feature domains, scale targets, accessibility (WCAG 2.1 AA), tech stack selection, CI/CD strategy

Implementation Guidance:

• IMPLEMENTATION_GUIDE.md (588 lines) - Code scaffolds for FastAPI/Next.js, Docker configs, environment templates, testing boilerplate
• api/BACKEND_API_SPEC.md (177 lines) - 40+ REST endpoints with request/response schemas, WebSocket events
• ARCHITECTURE_DIAGRAMS.md (916 lines) - ASCII diagrams: system architecture, layer structures, authentication flows, data pipelines

Navigation:

• README_FRONTEND_ARCHITECTURE.md (486 lines) - Master index with reading recommendations per role
• FRONTEND_ARCHITECTURE_SUMMARY.md (533 lines) - Executive overview for stakeholders

Architecture Decisions

Stack: FastAPI (Python 3.11+) backend + Next.js 14 (TypeScript) frontend

• FastAPI: Native async for concurrent LLM calls, automatic OpenAPI docs, seamless integration with existing Python codebase
• Next.js: SSR for performance (<2s FCP target), App Router, type-safe by default

State Management: Zustand (UI state) + TanStack Query (server state)

• Clear separation: ephemeral UI state vs cached API responses

Real-Time: Socket.IO with WebSocket + polling fallback

• Research/critique progress streaming, automatic reconnection

Security: OAuth2 + JWT (15min access, 7d refresh), bcrypt hashing, RBAC, rate limiting per user/IP

Infrastructure: PostgreSQL 15+ (relational), Redis 7+ (sessions/queue), Celery (long-running tasks), Docker Compose

Feature Integration Points

Maps 6 core domains to existing codebase:

1. Research Synthesis → src/syncretic_catalyst/
2. Critique & Review → src/council/
3. Literature Search → src/research_apis/
4. Document Generation → src/latex/
5. User Management → New implementation required
6. System Administration → config.json, src/config_loader.py

Implementation Roadmap

16-week plan across 6 phases:

1. Foundation (weeks 1-3): Auth + infrastructure
2. Research (weeks 4-6): End-to-end workflow with real-time progress
3. Critique (weeks 7-9): Document upload → review generation
4. Search (weeks 10-11): Unified literature search UI
5. Polish (weeks 12-13): Performance optimization, WCAG 2.1 AA compliance
6. Advanced (weeks 14+): Schema-driven UI, internal plugin system

Scale Targets

Phase 1: 10-50 concurrent users, 100K-1M embeddings, <200ms API p95, <2s UI FCP
Phase 2: 100-500 users, 1M-10M embeddings

Scaling strategy: Stateless API workers (horizontal), Celery for CPU-intensive ops, Redis caching, database query optimization

Example: Feature Module Pattern

// Modular feature with manifest-based registration
export const researchFeatureManifest: FeatureManifest = {
  id: 'research',
  routes: [
    { path: '/research', component: lazy(() => import('./Dashboard')), permission: 'research.view' },
    { path: '/research/:id', component: lazy(() => import('./Detail')), permission: 'research.view' }
  ],
  navItems: [{ label: 'Research', icon: 'FlaskConical', path: '/research' }],
  permissions: ['research.view', 'research.create', 'research.delete']
};

// Auto-registered at runtime, code-split, permission-gated
featureRegistry.register(researchFeatureManifest);

Clean Architecture Compliance

• Strict layering: Presentation → Application → Domain → Infrastructure
• Dependency inversion: outer layers depend on inner via interfaces
• 500 LOC file size limit enforced
• Framework-independent domain models
• Testability: dependency injection throughout, 80%+ coverage target

All specifications ready for implementation. Start at docs/README_FRONTEND_ARCHITECTURE.md for navigation.

Original prompt

High-level proposal (will refine once you confirm backend details).
I’ll need some specifics about Cogito’s backend to tailor this precisely:

1. What protocols are exposed? (REST, GraphQL, WebSockets, gRPC via proxy?)
2. How does authentication/authorization work? (OAuth2/OIDC, JWT, API keys, sessions?)
3. What are the core feature domains? (e.g., user management, analytics, knowledge graphs, task orchestration, data ingestion, reporting?)
4. Do any features require real‑time updates (notifications, streaming metrics)?
5. Any multi‑tenant concerns?
6. Expected scale (concurrent users, data volume) and performance constraints.
7. Accessibility / compliance targets (WCAG level? Internationalization?)
8. Preferred tech stack (React, Vue, Svelte, Next.js, Remix, etc.) or constraints.
9. Do you anticipate third‑party plugins or internal-only extensibility?
10. CI/CD environment and hosting (Vercel, Cloudflare Pages, self-hosted, Docker behind Nginx, etc.)
    Let me know these and I’ll tailor concrete module boundaries, data contracts, and example code scaffolds.

Below is a comprehensive, extensible front-end architecture you can adopt now, with placeholders that will snap to your backend once details arrive.

---

Architecture Goals

• Full feature coverage of current backend
• Rapid addition of new backend capabilities without refactoring core
• Support horizontal expansion (new feature domains) and vertical expansion (deeper functionality per domain)
• Strong separation of concerns: UI, data access, state, cross-cutting services
• Pluggable feature modules loaded dynamically (code-splitting)
• Schema or contract-driven UI generation where possible
• Consistent design system + theming
• Observability, testability, and resilience baked in

Recommended Technology Stack (adjustable)

• Framework: Next.js (for SSR/SSG, routing, performance) or Remix (if you want enhanced data conventions). If purely SPA, use Vite + React.
• Language: TypeScript everywhere.
• State: Domain-scoped stores using Redux Toolkit or Zustand (Redux better for predictable enterprise patterns; Zustand simpler; can mix).
• Data Layer:
  • If REST: TanStack Query for caching, invalidation, optimistic updates.
  • If GraphQL: Apollo Client or urql with codegen (schema-driven types).
  • Real-time: Socket.io, native WebSocket wrapper, or GraphQL subscriptions provider.
• Styling: Tailwind + Radix UI + CSS Variables for design tokens OR a fully custom component library with Storybook.
• Forms: React Hook Form + Zod (schema validation). If GraphQL, auto-generate form defaults from schema.
• Build: Turborepo if multi-package (design-system, core-services, feature modules).
• Testing: Vitest/Jest (unit), Playwright/Cypress (e2e), Storybook interaction tests.
• Quality: ESLint (custom rules per layer), TypeScript strict, Lighthouse budget in CI.

---

Project Monorepo Structure (example)
/apps
/web (Next.js front-end shell)
/admin (Optional separate app if needed)
/packages
/design-system (Shared UI components, tokens, icons)
/core-services (Auth, API client factories, logging, error mapping)
/feature-user (User domain: pages, components, hooks, slices)
/feature-analytics (Analytics domain)
/feature-content (Content/domain-specific logic)
/feature-realtime (Event stream visualizations)
/configs
eslint/, tsconfig/, jest/, storybook/
/scripts
codegen, build, lint, release

Each feature package exports:

• Routes (metadata)
• Navigation items
• Store slices / hooks
• Service adapters
• Component registry
• Permissions manifest

---

Modular Feature Pattern
Define a FeatureManifest interface:
interface FeatureManifest {
id: string;
version: string;
routes: RouteDef[];
navItems?: NavItem[];
permissions?: PermissionDef[];
register?(ctx: AppContext): void;
unload?(): void;
}

On app boot:

1. Load static feature manifests (core).
2. Optionally fetch dynamic manifest index from backend (to allow backend-driven UI enabling).
3. Dynamically import feature bundles (code splitting).
4. Register their routes, nav, permissions, and inject store slices.

Vertical Expansion

• Each feature declares capability descriptors (e.g., analytics supports dashboards, alerts, exports).
• Backend advertises new capabilities; manifest expands; front-end UI either:
  • Generates new panels via schema (e.g., new metric type = auto-card)
  • Or provides plugin slot for manual enhancement.

Horizontal Expansion

• Adding a new domain = create /feature-newDomain package implementing manifest + service adapters; no core changes.

---

Data Access Layer
Create a unified service factory:
class ApiClient {
constructor(private auth: AuthProvider, private config: ApiConfig) {}
request(req: ApiRequest): Promise { /* injec...

Custom agent used: RC-Apex
Apex Methodological & Analytic Reviewer

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.