Architecture

This document describes the overall architecture of the Lakra annotation and evaluation system.

Overview

Lakra is a modern web application built with a serverless architecture using React for the frontend and Supabase as the backend-as-a-service (BaaS).

┌─────────────────────────────────────────────────────────┐
│                    Client (Browser)                      │
│  ┌──────────────────────────────────────────────────┐   │
│  │           React 19 Application                    │   │
│  │  ┌──────────┐  ┌──────────┐  ┌────────────────┐  │   │
│  │  │  Pages   │  │Components│  │  Context/State │  │   │
│  │  └──────────┘  └──────────┘  └────────────────┘  │   │
│  │  ┌──────────┐  ┌──────────┐  ┌────────────────┐  │   │
│  │  │ Services │  │  Utils   │  │     Hooks      │  │   │
│  │  └──────────┘  └──────────┘  └────────────────┘  │   │
│  └──────────────────────────────────────────────────┘   │
└────────────────────┬────────────────────────────────────┘
                     │ HTTPS / WebSocket
                     ▼
┌─────────────────────────────────────────────────────────┐
│                    Supabase (Backend)                    │
│  ┌────────────┐  ┌──────────┐  ┌─────────────────────┐ │
│  │   Auth     │  │PostgreSQL│  │   Storage (S3)      │ │
│  │  (JWT)     │  │  + RLS   │  │ (Voice Recordings)  │ │
│  └────────────┘  └──────────┘  └─────────────────────┘ │
│  ┌────────────┐  ┌──────────┐  ┌─────────────────────┐ │
│  │Edge Funcs  │  │Realtime  │  │    API (REST)       │ │
│  │(Optional)  │  │Listeners │  │                     │ │
│  └────────────┘  └──────────┘  └─────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Architecture Principles

1. Serverless-First

No traditional backend server to maintain
Supabase handles all server-side operations
Scales automatically with demand
Reduces operational complexity

2. Client-Side Rendering

React handles all UI rendering
Fast, interactive user experience
State management via React Context
Client-side routing with React Router

3. Security by Default

Row Level Security (RLS) at database level
JWT-based authentication
Role-based access control (RBAC)
Secure HTTP-only operations

4. Mobile-First Design

Responsive layouts work on all screen sizes
Progressive Web App (PWA) capabilities
Optimized for touch interfaces
Adaptive UI based on device

Frontend Architecture

Technology Stack

React 19: Core UI library
TypeScript: Type-safe development
Vite: Lightning-fast build tool and dev server
TailwindCSS: Utility-first styling
React Router: Client-side routing
GSAP: Animations
Supabase Client: Backend integration

Project Structure

src/
├── components/          # React components
│   ├── auth/           # Authentication components
│   ├── layout/         # Layout components (Navbar, Footer)
│   ├── modals/         # Modal dialogs
│   ├── pages/          # Page components
│   └── ui/             # Reusable UI components
├── contexts/           # React Context providers
│   └── AuthContext.tsx # Authentication state
├── hooks/              # Custom React hooks
│   └── useSEO.ts       # SEO meta tags
├── services/           # API services
│   ├── api.ts          # API wrappers
│   └── supabase-api.ts # Supabase client methods
├── types/              # TypeScript type definitions
│   └── index.ts        # Shared types
├── utils/              # Utility functions
│   ├── logger.ts       # Logging utilities
│   ├── seo.ts          # SEO utilities
│   └── supabase.ts     # Supabase client configuration
├── App.tsx             # Main application component
├── main.tsx            # Application entry point
└── index.css           # Global styles

Component Architecture

Component Hierarchy:

App
├── AuthProvider (Context)
├── Router
│   ├── Layout
│   │   ├── Navbar
│   │   ├── AnimatedBackground
│   │   └── Footer
│   └── Routes
│       ├── Public Routes
│       │   ├── Landing
│       │   ├── Login
│       │   ├── Register
│       │   └── About
│       ├── Protected Routes (Authenticated)
│       │   ├── AnnotatorDashboard
│       │   ├── AnnotationInterface
│       │   ├── EvaluatorDashboard
│       │   ├── EvaluationInterface
│       │   └── AdminDashboard
│       └── Admin Routes
│           ├── UserManagement
│           ├── SentenceManagement
│           └── Analytics
└── Modals
    ├── GuidelinesModal
    ├── ConfirmationModal
    └── QuizModals

State Management

Authentication State:

Managed by AuthContext
Provides current user, role, and auth methods
Persisted via Supabase session management

Local State:

Component-level state with useState
Form state management
UI state (modals, loading, etc.)

Server State:

Fetched from Supabase in components
Real-time updates via Supabase listeners (optional)
Optimistic updates for better UX

Routing Strategy

Route Types:

Public Routes: Accessible without authentication
- Landing page (/)
- Login (/login)
- Register (/register)
- About (/about)
Accessible Routes: Available to both authenticated and non-authenticated users
- About page with different content
Protected Routes: Require authentication
- Dashboards
- Annotation interfaces
- Evaluation interfaces
Role-Based Routes: Require specific roles
- Admin routes (admin only)
- Annotator routes (annotator only)
- Evaluator routes (evaluator only)

Route Guards:

<ProtectedRoute adminOnly={true}>
  <AdminDashboard />
</ProtectedRoute>

Data Flow

User Action
    ↓
Component Event Handler
    ↓
Service Function (API call)
    ↓
Supabase Client
    ↓
[Network Request]
    ↓
Supabase Backend
    ↓
PostgreSQL + RLS
    ↓
[Network Response]
    ↓
Component State Update
    ↓
UI Re-render

Backend Architecture

Supabase Components

1. PostgreSQL Database

Features:

Fully managed PostgreSQL database
Row Level Security (RLS) policies
Real-time capabilities
Full-text search
Complex queries and joins

Schema Design:

Normalized relational structure
Foreign key relationships
Indexes for performance
Constraints for data integrity

See Database Schema for details.

2. Authentication (Supabase Auth)

Features:

Email/password authentication
Username-based login via RPC
JWT tokens (access + refresh)
Automatic session management
Secure password hashing

Authentication Flow:

User submits credentials
Supabase Auth validates
JWT tokens generated
Tokens stored in browser (localStorage)
Tokens sent with every request
RLS policies check user permissions

3. Storage (Supabase Storage)

Purpose: Voice recording storage

Features:

S3-compatible object storage
Private buckets with access policies
Signed URLs for secure access
Automatic MIME type detection

Bucket Structure:

voice-recordings/
├── {user_id}/
│   ├── {annotation_id}_voice.webm
│   └── {annotation_id}_voice.mp3

4. Row Level Security (RLS)

Purpose: Database-level access control

How it works:

Policies defined per table and operation (SELECT, INSERT, UPDATE, DELETE)
Policies use auth.uid() to identify current user
Policies check user role and ownership
Enforced at database level (can’t be bypassed)

Example Policy:

-- Users can only read their own profile
CREATE POLICY "Users can view own profile"
  ON users FOR SELECT
  USING (auth.uid() = id);

-- Admins can read all users
CREATE POLICY "Admins can view all users"
  ON users FOR SELECT
  USING (
    EXISTS (
      SELECT 1 FROM users
      WHERE id = auth.uid()
      AND role = 'admin'
    )
  );

5. Edge Functions (Optional)

Purpose: Custom serverless functions

Use Cases:

Complex business logic
Third-party API integrations
Background processing
Email notifications

Deployment:

supabase functions deploy function-name

Authentication Flow

Login Process

sequenceDiagram
    participant U as User
    participant C as Client (React)
    participant S as Supabase Auth
    participant DB as PostgreSQL

    U->>C: Enter email/username + password
    C->>S: signInWithPassword()
    S->>DB: Validate credentials
    DB-->>S: User data
    S-->>C: JWT tokens + session
    C->>C: Store tokens
    C->>DB: Fetch user profile (with RLS)
    DB-->>C: User data with role
    C-->>U: Redirect to role dashboard

Authorization Flow

sequenceDiagram
    participant C as Client
    participant API as Supabase API
    participant RLS as RLS Engine
    participant DB as Database

    C->>API: Request with JWT
    API->>RLS: Check policies
    RLS->>RLS: Extract user from JWT
    RLS->>DB: Query with user context
    DB-->>RLS: Filtered results
    RLS-->>API: Authorized data
    API-->>C: Response

Data Flow Patterns

Annotation Creation

User fills annotation form
Client validates input
Service calls Supabase API
RLS verifies user can create annotation
Database inserts annotation record
Database triggers update sentence status
Response sent to client
UI updates with new annotation
Navigate to next sentence

Quality Assessment

Evaluator selects annotation to review
Client fetches annotation + AI assessment
Evaluator validates/modifies scores
Client submits evaluation
RLS verifies evaluator role
Database inserts evaluation record
Database updates annotation metadata
Response confirms success
UI shows next pending evaluation

Performance Optimizations

Frontend

Code Splitting
- Vendor bundle (React, React-DOM)
- Router bundle (React Router)
- Lazy loading for routes (optional)
Build Optimizations
- Vite’s optimized bundling
- Tree shaking
- Minification
- Console removal in production
Runtime Optimizations
- Memoization (useMemo, useCallback)
- Debouncing user inputs
- Optimistic UI updates

Backend

Database
- Indexes on foreign keys
- Indexes on frequently queried columns
- Efficient RLS policies
- Connection pooling
API
- Selective field fetching
- Pagination for large datasets
- Caching strategies (if applicable)
Storage
- CDN for static assets
- Signed URL caching
- Optimized file formats (WebM for audio)

Security Architecture

Defense in Depth

Layer 1: Client Validation

Input validation
Client-side role checks
UI-level access control

Layer 2: Network

HTTPS only
CORS configuration
Rate limiting (via Supabase)

Layer 3: Authentication

JWT verification
Session timeout
Refresh token rotation

Layer 4: Authorization (RLS)

Database-level policies
Role-based access
Data ownership checks

Layer 5: Data

Encrypted at rest
Encrypted in transit
Secure password hashing

Threat Mitigation

SQL Injection:

Prevented by Supabase parameterized queries
No raw SQL from client

XSS (Cross-Site Scripting):

React escapes output by default
Content Security Policy headers

CSRF (Cross-Site Request Forgery):

JWT tokens (not cookies)
Origin verification

Unauthorized Access:

RLS policies enforce permissions
Role verification at multiple layers

Scalability Considerations

Horizontal Scaling

Supabase handles database scaling
CDN for static assets (Vercel)
Serverless functions scale automatically

Performance at Scale

Database connection pooling
Efficient query optimization
Caching strategies
Background job processing (if needed)

Data Growth

Archival strategies for old data
Partitioning for large tables
Storage optimization

Monitoring and Observability

Client-Side

Vercel Analytics integration
Error tracking (if configured)
Performance metrics

Server-Side

Supabase dashboard metrics
Database query performance
API response times
Error logs

Deployment Architecture

Development

Local Machine
├── Vite Dev Server (port 5173)
└── Supabase Project (cloud)

Production

Vercel (Frontend)
├── CDN (Global)
├── Edge Functions (Optional)
└── Static Build

Supabase (Backend)
├── Database (Regional)
├── Auth Service
├── Storage (S3)
└── API Gateway

Future Architecture Enhancements

Potential improvements:

Real-Time Collaboration
- Supabase Realtime for live updates
- Collaborative annotation features
Offline Support
- Service workers
- Local storage
- Sync when online
Advanced AI Integration
- Supabase Edge Functions for AI processing
- Third-party AI service integration
Analytics Pipeline
- Data warehouse integration
- Advanced reporting
- Machine learning insights

Architecture

Overview

Architecture Principles

1. Serverless-First

2. Client-Side Rendering

3. Security by Default

4. Mobile-First Design

Frontend Architecture

Technology Stack

Project Structure

Component Architecture

State Management

Routing Strategy

Data Flow

Backend Architecture

Supabase Components

1. PostgreSQL Database

2. Authentication (Supabase Auth)

3. Storage (Supabase Storage)

4. Row Level Security (RLS)

5. Edge Functions (Optional)

Authentication Flow

Login Process

Authorization Flow

Data Flow Patterns

Annotation Creation

Quality Assessment

Performance Optimizations

Frontend

Backend

Security Architecture

Defense in Depth

Threat Mitigation

Scalability Considerations

Horizontal Scaling

Performance at Scale

Data Growth

Monitoring and Observability

Client-Side

Server-Side

Deployment Architecture

Development

Production

Future Architecture Enhancements

See Also