Platform Functioning

Discover how CyberCTF works behind the scenes and how to make the most of your learning experience.

🏗️ Platform Architecture

Docker-Based Labs

Each lab runs in a completely isolated Docker container:

Isolated execution: No risk to your system
Consistent environments: Same setup for all users
Port mapping: Services exposed on localhost:3206
Auto-cleanup: Containers removed after use

GraphQL API

Modern API for efficient data fetching:

Single endpoint: All queries through /api/proxy/graphql
Flexible queries: Request exactly what you need
Real-time data: Up-to-date progress and stats
Authentication: Secure OIDC token-based access

Cloud Infrastructure

Vercel hosting: Fast, reliable deployment
Environment variables: Secure configuration
Automatic scaling: Handle traffic spikes
Global CDN: Fast content delivery

🎮 User Interface

Dashboard (`/dashboard`)

Your central hub for tracking progress:

Statistics Cards:

Total Points: Cumulative score from all challenges
Your Rank: Position on the global leaderboard
Completed Challenges: Number of solved labs
Current Level: Based on points (Level = Points / 1000)

Quick Actions:

Recommended Lab: Easiest unsolved challenge
Continue Lab: Resume where you left off
Recent Activity: Your latest submissions
Achievements: Unlocked badges and milestones

Features:

Onboarding flow for new users
Achievement notifications
Progress visualization
Contextual tutorials

Labs Page (`/labs`)

Browse and access all challenges:

Challenge Grid:

Category badges: Web, Crypto, Forensics, etc.
Difficulty indicators: 1-5 star rating
Points display: Reward for completion
Status icons: Completed, in-progress, locked

Filtering:

By difficulty level
By category
By completion status
Search by title

Launch Options:

Quick launch button (Launcher)
Docker commands tab
Deep link integration (cyberctf://)

Lab Detail Page (`/labs/[slug]`)

Individual challenge interface:

Lab Information:

Challenge description
Points and difficulty
Time estimate
Prerequisites

Launch Methods:

Launcher tab: One-click launch via deep link
Commands tab: Manual Docker commands
Copy buttons for easy use

Flag Submission:

Input field with format example
Submit button
Real-time feedback (success/error)
Attempt counter and warnings

Sidebar:

Lab environment status
Running indicator
Stop lab button
Environment details (runtime, image, timeout)

Guided Mode (optional):

Step-by-step questions
Progressive hints
Point penalties for help
Educational guidance

Leaderboard Page (`/leaderboard`)

Global user rankings:

Leaderboard Table:

Rank: Position (1st, 2nd, 3rd with icons)
Username: Player identifier
Points: Total score
Level: Calculated level (Points / 1000)
Your row: Highlighted in color

Features:

Server-side rendering for performance
Automatic user highlighting
Avatar display
Level badges

Profile Page (`/profile`)

Your personal statistics:

Profile Card:

Avatar and username
Email address
Join date
Share profile button

Statistics:

Total points earned
Global rank
Challenges completed
Average lesson progress

Recent Activity:

Last 3 submissions
Challenge titles
Points earned
Submission dates

Actions:

Edit profile (link to Settings)
View achievements
Share progress

Statistics Page (`/stats`)

Platform-wide analytics:

Global Stats:

Total registered users
Total available challenges
Total submissions made
Platform activity level

Top Users:

Top 10 performers
Points and submission counts
Visual ranking

Challenge Popularity:

Most attempted challenges
Success rates
Average attempts
Popular categories

Category Breakdown:

Challenges by category
Distribution chart
Completion rates

Settings Page (`/settings`)

Account management:

Profile Settings:

Update username
Email (read-only)
Avatar upload (future)

Notifications:

Email notifications toggle
Challenge completion alerts
Achievement notifications

Privacy:

Public profile visibility
Leaderboard participation

Account:

Change password (via OIDC)
Delete account
Export data

Security:

Active sessions list
Logout from all devices
Two-factor authentication (future)

🔐 Authentication System

OIDC Flow

Industry-standard authentication:

Sign Up (/sign-up): Create account with email/password
Email Verification: Confirm your email address
Sign In (/sign-in): Login with credentials
Token Generation: Receive access and refresh tokens
Auto-refresh: Tokens renewed automatically in background

Token Management

Access Token: Short-lived (15-60 min)
Refresh Token: Long-lived, device-specific
ID Token: User information (email, username)
Secure storage: HTTP-only cookies

Session Handling

Persistent sessions: Stay logged in
Automatic logout: After inactivity
Logout endpoint: /api/auth/logout
Session refresh: /api/auth/refresh

📊 Scoring System

Points Calculation


Base Points = Challenge difficulty × 100
Speed Bonus = Max 20% for fast completion
Hint Penalty = -5 points per hint used
Final Score = Base + Bonus - Penalties

Level System


Level = Floor(Total Points / 1000) + 1
Example: 2,500 points = Level 3

Ranking Algorithm

Calculate total points per user
Sort users by points (descending)
Assign ranks sequentially
Handle ties by timestamp

🔄 Data Synchronization

Real-time Updates

GraphQL queries: Fetch latest data
SWR hooks: Automatic revalidation
Optimistic updates: Instant UI feedback
Background refresh: Keep data current

Caching Strategy

Client-side: SWR cache
Server-side: Next.js caching
No-store: Real-time data (leaderboard)
Revalidation: On focus, reconnect

State Management

React hooks: Local component state
Context API: Authentication state
LocalStorage: Lab running status, preferences
Cookies: Authentication tokens

🛠️ Integrated Tools

Challenge Interface

Flag input: Format validation
Submit button: Real-time feedback
Hint system: Progressive assistance
Progress tracking: Step completion

Docker Integration

Deep links: cyberctf://start?challengeId=...
Auto-detection: Launcher availability
Fallback: Manual Docker commands
Copy helpers: One-click command copy

GraphQL API Features

User queries: Profile, submissions, progress
Challenge queries: List, detail, search
Leaderboard: Global and category rankings
Mutations: Submit flags, update profile

📱 Responsive Design

Mobile Optimization

Responsive navbar: Hamburger menu on mobile
Touch-friendly: Large tap targets
Adaptive layouts: Grid to stack on small screens
Mobile navigation: Sheet/drawer components

Desktop Features

Side navigation: Always visible menu
Multi-column layouts: Efficient space use
Hover states: Interactive feedback
Keyboard shortcuts: Power user features

🚀 Performance

Optimization Techniques

Code splitting: Load only what’s needed
Dynamic imports: Lazy load components
Image optimization: Next.js Image component
Bundle analysis: Monitor bundle size

Loading States

Skeleton screens: Smooth loading experience
Progressive rendering: Show content as it loads
Error boundaries: Graceful error handling
Retry mechanisms: Auto-retry failed requests