Platform Concepts

Understanding the core concepts and architecture of the Leyu platform.

---

Quick Navigation

• Backend Architecture
• Frontend Architecture
• Mobile Architecture
• User Roles & Access

---

Backend Architecture

Executive Summary

The Leyu Backend is a scalable, server-side application built on Node.js using NestJS.
It leverages TypeScript for type safety and TypeORM as the Object-Relational Mapper (ORM).

The system is modular, ensuring each feature (e.g., Users, Auth, Projects) is self-contained.

Architectural Design Patterns

• Modular Pattern: Modules encapsulate providers, controllers, and services.
• Dependency Injection (DI): NestJS handles class instantiation and injection.
• Data Mapper Pattern: Entities define database schema; Repositories manage data.
• Middleware & Interceptors: For logging, response transformation, and monitoring.

Structural Components

A. Module System

• AppModule: Root module importing all feature modules.
• Feature Modules: Groups related code (e.g., UserModule, AuthModule).
• Shared Modules: Common utilities like database connections or configuration.

B. Controllers (Traffic Routing)

• Role: Handles incoming HTTP/REST requests and returns responses.
• Decorators: @Controller(), @Get(), @Post() to define routes.

C. Services (Business Logic)

• Role: Providers that contain core logic (@Injectable()).
• Interaction: Services call TypeORM Repositories to fetch or persist data.

D. TypeORM Entities & Repositories

• Entities: Classes mapped to database tables using decorators (@Entity(), @PrimaryGeneratedColumn(), @Column()).
• Repositories: Abstraction layer for database queries (Save, Find, Delete).

Data Architecture

• Database: PostgreSQL (or MySQL)
• Migrations: TypeORM Migration API manages schema changes version-by-version
• Relations: @OneToMany, @ManyToOne, @ManyToMany for complex structures

Technology Stack

Component	Technology
Runtime	Node.js
Language	TypeScript
Framework	NestJS
ORM	TypeORM
Validation	class-validator & class-transformer
API Documentation	Swagger (@nestjs/swagger)
Package Manager	npm / yarn / pnpm

Request Lifecycle

1. Request: Client hits an endpoint
2. Middleware: Tasks like CORS or logging
3. Guards: Authentication checks (e.g., JWT Guard)
4. Interceptors (Pre): Transform data before controller
5. Pipes: Validate DTOs
6. Controller: Route to the correct service
7. Service: Execute logic and access database
8. Interceptors (Post): Map database entity to clean API response
9. Response: Client receives JSON

Security & Observability

• Guards: Role-Based Access Control (RBAC)
• Environment Config: Managed via @nestjs/config and .env
• Error Handling: Custom Exception Filters to prevent leaking stack traces

---

Frontend Architecture

Executive Summary

The Leyu Frontend is built on Next.js 15 with App Router and React 19.
It is feature-based, organized by domain modules (Projects, Tasks, Users, Reviews).

Architectural Design Patterns

• App Router Pattern: File-system-based routing, server components by default, nested layouts, route groups
• Component-Based Architecture:
  • Presentational Components: src/components/ui/
  • Feature Components: src/app/components/
  • Page Components: Route-level composition

State Management

• Server State: TanStack Query
• Client State: Zustand
• Form State: React Hook Form
• URL State: Next.js searchParams

Route System Structure

app/
├── (auth)/              # Authentication routes
├── (dashboard)/         # Protected dashboard routes
│   ├── superadmin/      # SuperAdmin pages
│   ├── projectmanager/  # Project Manager pages
│   ├── facilitator/     # Facilitator pages
│   └── reviewer/        # Reviewer pages
├── (public)/            # Public-facing pages
├── (shared)/            # Shared route components
└── api/                 # API routes
    └── auth/            # NextAuth.js endpoints

Authentication & Authorization

• NextAuth.js: Credentials-based authentication, JWT strategy, HTTP-only cookies
• Roles: SuperAdmin, ProjectManager, Facilitator, Reviewer

Frontend Tech Stack

Component	Technology
Runtime	Node.js
Language	TypeScript 5.8
Framework	Next.js 15.4 (App Router)
UI Library	React 19
Styling	Tailwind CSS 4.1
Component Library	Radix UI + shadcn/ui
State Management	TanStack Query + Zustand
Form Handling	React Hook Form + Zod
HTTP Client	Axios 1.12
Data Tables	TanStack Table 8.21
Audio Processing	WaveSurfer.js 7.9
Package Manager	pnpm

---

Mobile Architecture

Executive Summary

Leyu Mobile is a Flutter-based app for data collection.
It uses Clean Architecture with GetX for state management.

Architecture Layers

Presentation Layer
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Pages (UI) │ │ Widgets │ │ Controllers │
└─────────────┘ └─────────────┘ └─────────────┘

Domain Layer
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Entities │ │ Use Cases │ │ Repository │
└─────────────┘ └─────────────┘ └─────────────┘

Data Layer
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Models (DTOs)││ Data Sources│ │ Repository │
└─────────────┘ └─────────────┘ └─────────────┘

Mobile Tech Stack

Category	Technology	Purpose
Framework	Flutter 3.5.0+	Cross-platform development
Language	Dart 3.5.0+	Programming language
State Management	GetX	Reactive state + DI
HTTP Client	Dio	REST API communication
Local Database	Hive	NoSQL local storage
Secure Storage	Flutter Secure Storage	Encrypted credentials
Audio Recording	record	Audio capture
Audio Playback	just_audio	Audio playback
Push Notifications	OneSignal 5.2.5	Real-time notifications
Environment Config	flutter_dotenv	Environment variables

Feature Modules

• Authentication: Phone number OTP, login, token management
• Home: Task listing, filtering, detail, audio/text submission
• Profile: View/edit profile, statistics, logout
• Notification: Read/unread status, details, badge counts

Supported Task Types

• Speech-to-Text: Display text → Record audio → Submit
• Text-to-Speech: Play audio → Transcribe → Submit text
• Text-to-Text: Display source → Enter target → Submit

---

User Roles & Access

Role	Responsibilities
Project Manager	Oversees projects, manages teams, coordinates data collection
Reviewer	Reviews and validates submitted data
Contributor	Submits data through audio and text
Facilitator	Assists contributors, manages local collection activities

---

Data Flow

1. Contributors submit audio/text via mobile app
2. Data uploaded to backend and stored securely
3. Reviewers validate quality and accuracy
4. Approved data added to dataset
5. Project managers export datasets for AI/ML training