Skip to main content

System Architecture Overview

High-level overview of Agentification Academy's architecture and component relationships.

System Components​

┌─────────────────────────────────────────────────────────────────┐
│                      Agentification Academy                       │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                      Frontend Layer                              │
├─────────────────────────────────────────────────────────────────┤
│ • React + Vite                   (src/components, src/pages)    │
│ • Supabase JS Client             (Authentication, Real-time)    │
│ • React Router                   (Client-side routing)          │
│ • TipTap Editor                  (Rich content editing)         │
│ • Cloudinary Integration         (Image management)             │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      API Layer (Backend)                         │
├─────────────────────────────────────────────────────────────────┤
│ • Python/Flask REST API          (src/routes/*.py)             │
│ • Supabase Service Role Client   (Direct DB access)            │
│ • Email Service                  (SMTP, notifications)         │
│ • Vercel Edge Functions          (serverless tasks)            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      Data & Services Layer                       │
├─────────────────────────────────────────────────────────────────┤
│ • Supabase PostgreSQL            (Primary database)            │
│ • Supabase Auth                  (User authentication)         │
│ • Supabase Realtime              (Live data sync)              │
│ • Cloudinary API                 (CDN, image transforms)       │
│ • YouTube Data API               (Video metadata)              │
│ • Google Analytics 4             (Event tracking)              │
│ • SMTP Server                    (Email delivery)              │
└─────────────────────────────────────────────────────────────────┘

Technology Stack​

Frontend​

  • Framework: React 18 with Vite
  • Styling: CSS + Tailwind CSS + Premium Dark Theme
  • Routing: React Router v6
  • Editor: TipTap (rich text editing)
  • Charts: Mermaid diagrams
  • State Management: React Hooks + Context API
  • API Client: Supabase JS Client (real-time subscriptions)

Backend​

  • Runtime: Python 3.8+
  • Framework: Flask (lightweight REST API)
  • Database ORM: SQLAlchemy (via Supabase client)
  • Async: Background tasks with threading
  • Email: SMTP via IONOS or similar

Database​

  • Primary: Supabase PostgreSQL (managed)
  • Schema: 23 tables covering users, courses, content, enrollments
  • Auth: Supabase Auth (JWT tokens)
  • Realtime: Supabase Realtime for live updates
  • Security: Row-level security (RLS) policies

External Services​

  • Authentication: Supabase Auth
  • Database: Supabase PostgreSQL
  • Image CDN: Cloudinary (transformations, optimization)
  • Video: YouTube Data API (metadata, thumbnails)
  • Analytics: Google Analytics 4 (GA4)
  • Email: SMTP (IONOS or custom)
  • Deployment: Vercel (frontend + serverless), Supabase (backend)

Architecture Patterns​

1. Service Layer Organization​

Services are organized by domain:

src/services/
├── courses/              (enrollment, lessons, progress)
├── content/              (CRUD, interactions, legal)
├── media/                (Cloudinary, YouTube)
├── marketing/            (newsletters, waitlist, careers)
├── monitoring/           (analytics, notifications)
└── backend/              (database, email services)

Pattern: Each domain has focused, single-responsibility services.

2. API-First Design​

Frontend doesn't talk directly to Supabase (mostly). Instead:

React Component
    ↓
Service Layer (src/services/*.js)
    ↓
Backend API Routes (src/routes/*.py)
    ↓
Supabase (or External APIs)

Benefits:

  • Centralized business logic
  • Easier to implement caching
  • Better security (RLS on backend)
  • Unified error handling

3. Real-Time Updates​

For live data (courses, content):

Frontend Subscribes
    ↓
Supabase Realtime Channel
    ↓
Database Changes
    ↓
Broadcast to Subscribed Clients

Used for: Track enrollment, lesson progress, content updates

4. Authentication Flow​

User Login
    ↓
Supabase Auth (JWT token)
    ↓
Store in localStorage + Session
    ↓
Include in API requests (Authorization header)
    ↓
Backend validates with Supabase

5. Asset Pipeline​

Images and videos follow this flow:

User Upload
    ↓
Cloudinary (client-side upload)
    ↓
CDN (fast delivery globally)
    ↓
Transformations (resize, optimize, format)
    ↓
Database URL Storage (optional)

Data Flow Examples​

Course Enrollment​

1. User clicks "Enroll"
   ↓
2. EnrollmentModal component
   ↓
3. enrollments.js service calls /api/enrollments POST
   ↓
4. Backend validates user & course
   ↓
5. Insert into enrollments table
   ↓
6. Send welcome email
   ↓
7. Frontend updates UI (real-time via Supabase)
   ↓
8. User redirected to course

Content Creation​

1. Admin uses ContentEditor
   ↓
2. content.js service calls /api/content POST
   ↓
3. TipTap JSON → HTML conversion
   ↓
4. Images uploaded to Cloudinary
   ↓
5. Backend inserts/updates content table
   ↓
6. Search index updated
   ↓
7. Users see content on homepage

Real-Time Progress​

1. User watches lesson video
   ↓
2. VideoPlayerModal tracks watch time
   ↓
3. updateLessonProgress() called
   ↓
4. Backend updates lesson_progress table
   ↓
5. Supabase Realtime broadcasts
   ↓
6. Dashboard updates in real-time
   ↓
7. Progress bar reflects instantly

Deployment Architecture​

Development​

  • Frontend: npm run dev (Vite dev server on :5173)
  • Backend: python main.py (Flask on :5001)
  • Database: Supabase (cloud, same as production)

Production​

  • Frontend: Vercel (static build + serverless functions)
  • Backend: Vercel (Python serverless) or dedicated server
  • Database: Supabase (production instance)
  • CDN: Vercel CDN + Cloudinary CDN
  • DNS: Vercel managed

Environment Separation​

Development:
├── Frontend: localhost:5173
├── Backend: localhost:5001
└── Database: Supabase staging project

Production:
├── Frontend: agentification.academy (Vercel)
├── Backend: Vercel Edge Functions
└── Database: Supabase production project

Security Architecture​

Frontend Security​

  • JWT tokens stored in secure cookies/localStorage
  • CORS headers prevent unauthorized domain access
  • CSP headers prevent XSS attacks
  • Environment variables only expose anon keys

Backend Security​

  • Service role key (bypasses RLS) only used on backend
  • All user data validated before database operations
  • Row-level security (RLS) enforces access control
  • Email operations authenticated via JWT
  • API endpoints rate-limited and logged

Database Security​

  • Row-level security policies on sensitive tables
  • Users can only see their own data
  • Admins have elevated permissions
  • Encryption at rest and in transit
  • Regular backups to Supabase

Scalability Considerations​

Current Limits​

  • Frontend: Vercel auto-scales, 10MB bundle size warning
  • Backend: Supabase connection pooling (20 connections)
  • Database: Postgres can handle 100K+ concurrent users
  • Storage: Cloudinary unlimited images, YouTube quota 100/day

Future Optimizations​

  1. Implement caching layer (Redis)
  2. Database query optimization (indexes, partitioning)
  3. Image CDN with WebP conversion
  4. Implement job queues (Celery) for long tasks
  5. Separate read/write replicas for database
  6. GraphQL API for flexible data fetching

References​

Last Updated: 2025-12-24

For questions about specific components, see the Documentation Index.