Neura Market
Back to .md Directory
ARCHITECTURE.md

Frontend Development Rules

globs: src/app/**/*.tsx src/components/**/*.tsx src/hooks/**/*.ts src/lib/**/*.ts

ssdeanx
May 2, 2026
0 downloads
1 views
ai agent rag copilot workflow
View source

trigger: glob globs: src/app//*.tsx src/components//.tsx src/hooks/**/.ts src/lib/**/*.ts

Frontend Development Rules

๐ŸŽจ NEXT.JS 15 APP ROUTER REQUIREMENTS (ARCHITECTURE)

App Router Structure

  • MUST use App Router with proper route grouping: (playground), (public)
  • MUST implement proper layout composition: root โ†’ group โ†’ page
  • MUST use server components by default, mark client with 'use client'
  • MUST follow loading.tsx, error.tsx, not-found.tsx patterns

Route Organization

src/app/
โ”œโ”€โ”€ (playground)/          # Protected playground features
โ”‚   โ”œโ”€โ”€ layout.tsx         # CopilotKit provider setup
โ”‚   โ”œโ”€โ”€ page.tsx           # Main agent chat
โ”‚   โ”œโ”€โ”€ multi-agent/       # Multi-agent workflows
โ”‚   โ”œโ”€โ”€ codegraph/         # Code analysis
โ”‚   โ””โ”€โ”€ settings/          # Configuration
โ”œโ”€โ”€ (public)/              # Public marketing pages
โ”‚   โ”œโ”€โ”€ about/             # About page
โ”‚   โ”œโ”€โ”€ docs/              # Documentation
โ”‚   โ””โ”€โ”€ features/          # Features page
โ”œโ”€โ”€ api/                   # API routes
โ”‚   โ””โ”€โ”€ copilotkit/        # CopilotKit endpoints
โ”œโ”€โ”€ auth/                  # Authentication pages
โ””โ”€โ”€ layout.tsx             # Root layout

Layout Composition Pattern

// Root layout - global providers
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className="dark">
      <body className={cn(fontSans.variable, "antialiased")}>
        <Providers>
          {children}
        </Providers>
      </body>
    </html>
  );
}

// Group layout - specific providers
export default function PlaygroundLayout({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKitProvider runtimeUrl={process.env.NEXT_PUBLIC_COPILOTKIT_RUNTIME_URL}>
      <div className="min-h-screen bg-background">
        {children}
      </div>
    </CopilotKitProvider>
  );
}

๐ŸŽฏ REACT 19 PATTERNS (MODERN REACT)

Component Architecture

  • MUST use functional components with hooks
  • MUST implement proper TypeScript interfaces for all props
  • MUST use React.memo for expensive components
  • MUST implement proper error boundaries

State Management Patterns

// Local state with TypeScript
const [state, setState] = useState<StateType>(initialState);

// Complex state with useReducer
const [state, dispatch] = useReducer(reducer, initialState);

// Context for shared state
const ThemeContext = createContext<ThemeContextType | undefined>(undefined);

// Custom hooks for reusable logic
export function useLocalStorage<T>(key: string, initialValue: T) {
  // Implementation
}

Performance Optimization

  • MUST use useCallback for event handlers passed as props
  • MUST use useMemo for expensive computations
  • MUST implement proper dependency arrays
  • MUST use React.lazy for code splitting

๐ŸŽจ TAILWIND V4 INTEGRATION (STYLING SYSTEM)

Required Imports

import { cn, glassVariants, transform3D, modernGradients, animations } from '@/lib/tailwind-v4-utils';

Styling Patterns

  • MUST use cn() function for className composition
  • MUST implement container queries: @container/name
  • MUST use OKLCH colors: oklch(0.7 0.25 105)
  • MUST apply 3D transforms: perspective-normal rotate-x-5

Component Styling Template

export function Component({ className, ...props }: ComponentProps) {
  return (
    <div className={cn(
      // Base styles
      "relative overflow-hidden",
      // Container queries
      "@container/component",
      // Glass effects
      glassVariants.strong,
      // 3D transforms
      transform3D.card,
      // Electric theme
      "neon-border electric-pulse",
      // Custom className
      className
    )}>
      {/* Content */}
    </div>
  );
}

๐ŸŽญ FRAMER MOTION INTEGRATION (ANIMATIONS)

Required Animation Patterns

  • MUST use viewport triggers: viewport={{ once: true }}
  • MUST implement stagger animations for lists
  • MUST include 3D hover effects
  • MUST respect reduced motion preferences

Animation Templates

// Page entrance animation
<motion.div
  initial={{ opacity: 0, y: 50 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.8 }}
>

// List stagger animation
<motion.div
  variants={{
    hidden: { opacity: 0 },
    show: {
      opacity: 1,
      transition: {
        staggerChildren: 0.1
      }
    }
  }}
  initial="hidden"
  animate="show"
>

// 3D hover effect
<motion.div
  whileHover={{
    scale: 1.05,
    rotateY: 8,
    rotateX: 4,
    z: 20
  }}
  className={transform3D.card}
>

๐Ÿงฉ COMPONENT DEVELOPMENT (REUSABILITY)

Component Structure

interface ComponentProps {
  children?: React.ReactNode;
  className?: string;
  variant?: 'default' | 'primary' | 'secondary';
  size?: 'sm' | 'md' | 'lg';
}

/**
 * Component description
 *
 * @param props - Component props
 * @returns JSX element
 *
 * @example
 * ```tsx
 * <Component variant="primary" size="lg">
 *   Content
 * </Component>
 * ```
 *
 * @author Dean Machines Team
 * @date 2025-06-20
 * @model Claude Sonnet 4
 */
export function Component({
  children,
  className,
  variant = 'default',
  size = 'md'
}: ComponentProps) {
  return (
    <div className={cn(
      // Base styles
      "component-base",
      // Variants
      {
        'variant-default': variant === 'default',
        'variant-primary': variant === 'primary',
        'variant-secondary': variant === 'secondary',
      },
      // Sizes
      {
        'size-sm': size === 'sm',
        'size-md': size === 'md',
        'size-lg': size === 'lg',
      },
      className
    )}>
      {children}
    </div>
  );
}

๐Ÿ”ง CUSTOM HOOKS DEVELOPMENT (REUSABLE LOGIC)

Hook Development Pattern

interface UseHookOptions {
  enabled?: boolean;
  onSuccess?: (data: any) => void;
  onError?: (error: Error) => void;
}

export function useCustomHook(options: UseHookOptions = {}) {
  const [state, setState] = useState<StateType>(initialState);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);

  const { enabled = true, onSuccess, onError } = options;

  useEffect(() => {
    if (!enabled) return;

    const performAction = async () => {
      try {
        setLoading(true);
        setError(null);
        const result = await apiCall();
        setState(result);
        onSuccess?.(result);
      } catch (err) {
        const error = err instanceof Error ? err : new Error('Unknown error');
        setError(error);
        onError?.(error);
      } finally {
        setLoading(false);
      }
    };

    performAction();
  }, [enabled, onSuccess, onError]);

  return { state, loading, error };
}

๐Ÿ“ฑ RESPONSIVE DESIGN (MOBILE-FIRST)

Container Query Implementation

const ResponsiveComponent = () => (
  <div className={cn(
    "@container/responsive",
    "grid grid-cols-1",
    "@sm:grid-cols-2 @lg:grid-cols-3"
  )}>
    <div className="@sm:p-6 @lg:p-8">Content</div>
  </div>
);

๐Ÿ” AUTHENTICATION INTEGRATION (SUPABASE)

Auth Utilities Usage

import { createClient } from '@/utility/supabase/client';

const supabase = createClient();
const { data: { user } } = await supabase.auth.getUser();

๐ŸŽฏ PERFORMANCE OPTIMIZATION (EFFICIENCY)

Code Splitting Strategies

const PlaygroundPage = dynamic(() => import('./playground/page'), {
  loading: () => <LoadingSpinner />,
  ssr: false
});

๐Ÿงช TESTING REQUIREMENTS (QUALITY ASSURANCE)

Component Testing

import { render, screen } from '@testing-library/react';
import { expect, test } from 'vitest';

test('renders component correctly', () => {
  render(<Component />);
  expect(screen.getByRole('button')).toBeInTheDocument();
});

Related Documents

ARCHITECTURE.md

Design Document: BharatSeva AI

BharatSeva AI is a multi-agent orchestration system built on AWS using Amazon Bedrock Agents with Claude 3.5 Sonnet as the foundation model. The system deploys 10 AI agents (1 Master Orchestrator + 9 Specialist Agents) to assist India's informal sector workers in navigating government schemes across three domains: PM Vishwakarma (artisan credit), PMFBY (crop insurance), and BOCW (construction worker welfare).

aiagentclaude
0
101
Prachet-Dev-Singh
ARCHITECTURE.md

OpenClaw Enterprise Transformation Plan

Transform OpenClaw from a single-user personal AI assistant into a **dual-mode platform** that is simultaneously:

aiagentrag
0
47
mholovetskyi
ARCHITECTURE.md

Qwen Image and Edit: Open-sourcing and Local GGUF Generations with Lightning

Daniel Sandner, for article on https://sandner.art/

aillmrag
0
19
sandner-art
ARCHITECTURE.md

Qwen3-TTS โ€” Model Reference

Models: `Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice` and `Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice`

aillm
0
19
gabriele-mastrapasqua