# InfoSec Labs - Developer Guide

**Last Updated:** January 28, 2026

## 1. Project Overview
**InfoSec Labs** is a comprehensive cybersecurity training platform (Virtual SOC). It simulates real-world cyber threats, allowing users to investigate alerts, complete learning paths, and earn certifications.

The application includes:
*   **Virtual SOC:** A dashboard where users receive and investigate simulated security alerts.
*   **Academy:** A structured learning system with modules, tasks, and quizzes.
*   **Gamification:** XP, Badges, Leaderboards, and Streaks.
*   **Organization Management:** B2B features for companies to manage employee training.
*   **Subscription System:** Stripe integration for Monthly/Yearly pro plans.

---

## 2. Technology Stack

### Backend
*   **Runtime:** Node.js
*   **Framework:** Express.js
*   **Database:** MySQL (using `mysql2` driver with promises)
*   **Authentication:** JWT (JSON Web Tokens)
*   **Payments:** Stripe API
*   **AI Integration:** OpenAI API / Local LLM support (via system settings)

### Frontend
*   **Framework:** React 18
*   **Build Tool:** Vite
*   **Styling:** Tailwind CSS
*   **State Management:** React Context & Hooks (standard local state)

### Deployment
*   **Target:** cPanel / Linux Shared Hosting (runs via Node.js Selector)
*   **Process:** Automated build script (`prepare_cpanel.sh`) that bundles frontend, backend, and migrations.

---

## 3. Key Systems & Architecture

### A. Authentication & Roles (`authController.js`)
*   **Roles:** `normal`, `admin`, `alert-admin`, `pro`.
*   **Student Status:** Users with `.edu` emails or whitelisted domains are automatically marked as `is_student`.
    *   *Logic:* Checked on Register, Login (`getMe`), and via Admin Whitelist.
*   **Organization:** Users can belong to an Organization (B2B). The owner manages seats and billing.

### B. Database & Migrations (`migrateDb.js`)
*   **Auto-Migration:** The server runs `migrateDb.js` on every startup.
*   **Logic:** It checks for missing tables and columns and creates them if they don't exist.
*   **Benefit:** No manual SQL changes needed when deploying updates.

### C. Assignments & Operations
*   **Operations:** Large-scale scenarios consisting of multiple alerts.
*   **Alerts:** Individual security events. Can be "assigned" to users manually by admins or automatically.
*   **AI Generation:** Content (alerts/scenarios) can be generated via AI (`aiController.js`).

### D. Payments (`paymentController.js` & `stripeSyncLogic.js`)
*   **Provider:** Stripe.
*   **Flow:**
    1.  User clicks "Upgrade" -> `createCheckoutSession` -> Stripe Checkout Page.
    2.  Success -> Webhook (`/api/payments/webhook`) updates DB.
*   **Sync:** Admin Panel has a "Sync Stripe" button to fetch active subscriptions from Stripe and update the local DB (fixes mismatched statuses).

---

## 4. Project Structure

```
infoseclabs/
├── frontend/             # React Frontend
│   ├── src/
│   │   ├── components/   # Reusable UI components
│   │   ├── pages/        # Main route pages
│   │   ├── config.js     # Frontend API URL config
│   └── dist/             # Build output (generated via npm run build)
│
├── src/                  # Node.js Backend
│   ├── controllers/      # Business logic (AUTH, ADMIN, PAYMENT etc.)
│   ├── routes/           # API Endpoints definition
│   ├── services/         # Helper business logic (e.g. AI generator)
│   ├── utils/            # Shared utilities
│   ├── config/           # DB connection config
│   ├── app.js            # Express app entry point
│   ├── migrateDb.js      # Auto-migration script
│   └── server.js         # Server runner
│
├── project_deploy.zip    # Deployment package (generated)
├── prepare_cpanel.sh     # Deployment automation script
└── .env                  # Environment variables (API Keys, DB Creds)
```

---

## 5. Deployment Instructions

### Standard Deployment (cPanel)
1.  **Build:** Run `./prepare_cpanel.sh` in the root directory.
    *   This compiles the React frontend.
    *   Copies backend files.
    *   Creates `project_deploy.zip`.
2.  **Upload:** Upload `project_deploy.zip` to your server.
3.  **Extract:** Unzip into your application folder.
4.  **Install:** Run `npm install` in the server folder.
5.  **Restart:** Restart the Node.js application. Database migrations will run automatically.

### Manual SQL Fixes (If ever needed)
*   **Student Status:** If a new university domain is added, the system automatically runs:
    ```sql
    UPDATE users SET is_student = 1 WHERE email LIKE '%@newdomain.edu';
    ```

---

## 6. Common Issues & Solutions

*   **"Table 'xyz' doesn't exist":** Restart the server. `migrateDb.js` will create it.
*   **"Unknown column 'organization_id'":** Fixed in v1.2. Run `Sync Stripe` in Admin Panel to refresh data.
*   **Frontend 404s:** Ensure `.htaccess` is set up to redirect all requests to `index.html` (Single Page App routing).

---

**Developed for:** InfoSec Labs
**Documentation Generated by:** Antigravity AI
