taleem-kernel 1.0.0

package/.env

@@ -0,0 +1,5 @@
+
+JWT_SECRET=change_this_to_a_long_random_secret
+DATABASE_URL="file:./dev.db"
+
+SERVER_URL=https://taleem.help/api

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "taleem-kernel",
+  "version": "1.0.0",
+  "description": "Taleem data and business-logic kernel. HTTP is only an adapter.",
+  "type": "module",
+  "main": "./src/ServerKernel.js",
+  "exports": {
+    ".": "./src/ServerKernel.js"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@prisma/client": "^6.19.3",
+    "bcrypt": "^6.0.0",
+    "dotenv": "^17.4.2",
+    "jsonwebtoken": "^9.0.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "prisma": "^6.19.3",
+    "vitest": "^4.1.11"
+  },
+  "keywords": [
+    "taleem",
+    "kernel",
+    "education"
+  ],
+  "license": "ISC"
+}

package/prisma/schema.prisma

@@ -0,0 +1,121 @@
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "sqlite"
+  url      = env("DATABASE_URL")
+}
+
+enum ContentType {
+  ARTICLE
+  PLAYER
+  MCQ
+}
+
+enum CourseAccess {
+  OPEN
+  MEMBERS
+  SUBSCRIPTION
+}
+
+enum AdminRole {
+  ADMIN
+  SUPER_ADMIN
+}
+
+model Course {
+  slug        String       @unique
+  title       String
+  description String?
+  thumbnail   String?
+  access      CourseAccess @default(OPEN)
+  price       Int          @default(0)
+  groupings   String       @default("[]")
+}
+
+model User {
+  id              Int              @id @default(autoincrement())
+  email           String           @unique
+  password        String
+  name            String?
+  role            String           @default("student")
+  resource        String?
+  createdAt       DateTime         @default(now())
+  subscriptions   Subscription[]
+  communications  Communication[]
+}
+
+model Admin {
+  id          Int       @id @default(autoincrement())
+  email       String    @unique
+  password    String
+  courseSlugs String    @default("[]")
+  role        AdminRole @default(ADMIN)
+  isActive    Boolean   @default(true)
+  createdAt   DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+}
+
+model Library {
+  slug               String      @id
+  title              String
+  description        String?
+  thumbnail          String?
+  type               ContentType
+  body               String?
+  courseSlug         String
+  groupSlug          String
+  sortOrder          Int         @default(0)
+  allowCommunication Boolean     @default(true)
+  meta               String?
+  createdAt          DateTime    @default(now())
+  updatedAt          DateTime    @updatedAt
+}
+
+model Subscription {
+  id          Int       @id @default(autoincrement())
+  userId      Int
+  courseSlug  String
+  startsAt    DateTime  @default(now())
+  endsAt      DateTime?
+  amount      Int?
+  user        User      @relation(fields: [userId], references: [id])
+  cancelledAt DateTime?
+
+  @@index([userId])
+  @@index([courseSlug])
+}
+
+model Communication {
+  id             Int       @id @default(autoincrement())
+  userId         Int
+  librarySlug    String
+  type           String
+  meta           String?
+  message        String
+  authorResponse String?
+  isPublic       Boolean   @default(false)
+  readAt         DateTime?
+  createdAt      DateTime  @default(now())
+  updatedAt      DateTime  @updatedAt
+  user           User     @relation(fields: [userId], references: [id])
+
+  @@index([userId])
+  @@index([librarySlug])
+}
+model Svg {
+
+  slug      String   @id
+
+  title     String
+
+  body      String
+
+  tags      String   @default("[]")
+
+  createdAt DateTime @default(now())
+
+  updatedAt DateTime @updatedAt
+
+}

package/readme.md

@@ -0,0 +1,116 @@
+
+# Taleem Server Kernel Constitution
+
+### Purpose
+
+The **serverKernel** is the product. It contains all business logic and data access. HTTP is only an adapter.
+
+## Owns
+
+* Database (Prisma)
+* Validation
+* Business rules
+* Authentication
+* Authorization
+* Domain errors
+
+## Never owns
+
+* Express
+* Routes
+* `req` / `res`
+* HTML pages
+* Cookies
+* Headers
+* Static files
+* URL parsing
+
+## Authentication Boundary
+
+### HTTP Layer
+
+Responsible for:
+
+* Reading `Authorization` header
+* Reading cookies
+* Extracting bearer token
+* Passing token to kernel
+
+Never verifies anything.
+
+### Kernel
+
+Responsible for:
+
+* Verifying JWT
+* Loading user
+* Checking permissions
+* Checking subscriptions
+* Returning authenticated identity
+
+Never reads headers.
+
+## Public API Rules
+
+Every public method:
+
+* validates input
+* validates authentication (if required)
+* enforces authorization
+* throws explicit errors
+* never silently fails
+* never returns ambiguous `null`
+
+## Error Rules
+
+Errors are for developers.
+
+Every error answers:
+
+1. What failed?
+2. Why?
+3. Which method?
+4. Which object/user/resource?
+5. What should the caller check?
+
+Example:
+
+```text
+AuthenticationError
+Method : library.get()
+Reason : JWT expired
+User   : 31
+Token  : valid format, expired at 2026-07-27T09:10Z
+```
+
+## Story Rule
+
+Every feature must be explainable as a story.
+
+```
+HTTP
+↓
+Extract token
+↓
+Kernel
+↓
+Authenticate
+↓
+Authorize
+↓
+Business logic
+↓
+Return result
+↓
+HTTP formats response
+```
+
+No business logic is allowed before entering the kernel.
+
+---
+
+I would add one final principle because it will save you from years of debugging:
+
+> **The kernel trusts nothing and explains everything.**
+
+That one sentence should be visible at the top of the `serverKernel` folder. It captures the philosophy you've been moving toward: every input is validated, every decision is explicit, and every failure tells you exactly why it happened.

package/src/Auth.js

@@ -0,0 +1,105 @@
+///home/bilal-tariq/00--TALEEM/taleem-server/src/serverKernel/Auth.js
+
+import JWT from "./JWT.js";
+
+export default class Auth {
+
+	constructor(kernel) {
+		this.kernel = kernel;
+		this.jwt = new JWT(kernel);
+	}
+	// --------------------------------------------------
+	// Token Creation
+	// --------------------------------------------------
+	createUserToken(user) {
+
+		return this.jwt.sign({ id: user.id, type: "user" });
+
+	}
+
+	createAdminToken(admin) {
+
+		return this.jwt.sign({ id: admin.id, type: "admin" });
+
+	}
+
+	// --------------------------------------------------
+	// Authentication
+	// --------------------------------------------------
+
+	async authenticate(token) {
+
+		const { id, type } = this.verifyToken(token);
+
+		if (type === "user") return this.authenticateUser(id);
+
+		if (type === "admin") return this.authenticateAdmin(id);
+
+		this.fail("authenticate()", `Unknown identity type '${type}'.`);
+
+	}
+
+async authenticateUser(id) {
+
+	const user = await this.kernel.user.get(id);
+
+	if (!user)
+		this.fail(
+			"authenticateUser()",
+			`User '${id}' does not exist.`
+		);
+
+	return user;
+
+}
+
+async authenticateAdmin(id) {
+
+	const admin = await this.kernel.admin.get(id);
+
+	if (!admin)
+		this.fail(
+			"authenticateAdmin()",
+			`Admin '${id}' does not exist.`
+		);
+
+	return admin;
+
+}
+
+	verifyToken(token) {
+
+		try {
+
+			return this.jwt.verify(token);
+
+		}
+		catch (error) {
+
+			this.fail("verifyToken()", error.message);
+
+		}
+
+	}
+
+	// --------------------------------------------------
+	// Helpers
+	// --------------------------------------------------
+
+	fail(method, reason) {
+
+		throw new Error(
+			[
+				"",
+				"========================================",
+				"AUTHENTICATION FAILED",
+				"----------------------------------------",
+				`Method : Auth.${method}`,
+				`Reason : ${reason}`,
+				"========================================"
+			].join("\n")
+		);
+
+	}
+
+}

package/src/CommunicationPolicy.js

@@ -0,0 +1,34 @@
+// src/serverKernel/CommunicationPolicy.js
+
+export default class CommunicationPolicy {
+
+	constructor(kernel) {
+		this.kernel = kernel;
+	}
+
+	// --------------------------------------------------
+	// Require permission to create a new communication.
+	// --------------------------------------------------
+
+	async require(user) {
+
+		const MAX_OPEN_QUESTIONS = 5;
+
+		const count =
+			await this.kernel.communication.countUserOpenQuestions(
+				user.id
+			);
+
+		if (count >= MAX_OPEN_QUESTIONS) {
+
+			throw new Error(
+				`Maximum of ${MAX_OPEN_QUESTIONS} open questions reached.`
+			);
+
+		}
+
+		return true;
+
+	}
+
+}

package/src/Config.js

@@ -0,0 +1,26 @@
+// src/serverKernel/Config.js
+
+import dotenv from "dotenv";
+
+dotenv.config();
+
+export default class Config {
+
+	constructor() {
+
+		this.port = Number(
+			process.env.PORT ?? 9000
+		);
+
+		this.jwtSecret =
+			process.env.JWT_SECRET;
+
+		this.databaseUrl =
+			process.env.DATABASE_URL;
+
+		this.nodeEnv =
+			process.env.NODE_ENV ?? "development";
+
+	}
+
+}

package/src/JWT.js

@@ -0,0 +1,31 @@
+// src/serverKernel/JWT.js
+
+import jwt from "jsonwebtoken";
+
+export default class JWT {
+
+	constructor(kernel) {
+
+		this.kernel = kernel;
+
+	}
+
+	sign(payload) {
+
+		return jwt.sign(
+			payload,
+			this.kernel.config.jwtSecret
+		);
+
+	}
+
+	verify(token) {
+
+		return jwt.verify(
+			token,
+			this.kernel.config.jwtSecret
+		);
+
+	}
+
+}

package/src/Logger.js

@@ -0,0 +1,33 @@
+// src/serverKernel/Logger.js
+
+export default class Logger {
+
+	info(...args) {
+
+		console.log("[INFO]", ...args);
+
+	}
+
+	warn(...args) {
+
+		console.warn("[WARN]", ...args);
+
+	}
+
+	error(...args) {
+
+		console.error("[ERROR]", ...args);
+
+	}
+
+	debug(...args) {
+
+		if (process.env.NODE_ENV !== "production") {
+
+			console.log("[DEBUG]", ...args);
+
+		}
+
+	}
+
+}

package/src/ServerKernel.js

@@ -0,0 +1,139 @@
+///home/bilal-tariq/00--TALEEM/taleem-server-prod/src/serverKernel/ServerKernel.js
+import { PrismaClient } from "@prisma/client";
+
+import Config from "./Config.js";
+import Auth from "./Auth.js";
+import Logger from "./Logger.js";
+import CommunicationPolicy from "./CommunicationPolicy.js";
+import User from "./modules/User.js";
+import Admin from "./modules/Admin.js";
+import Library from "./modules/Library.js";
+import Course from "./modules/Course.js";
+import Communication from "./modules/Communication.js";
+import Subscription from "./modules/Subscription.js";
+import Image from "./modules/Image.js";
+import Audio from "./modules/Audio.js";
+import Svg from "./modules/Svg.js";
+
+class ServerKernel {
+
+	constructor() {
+
+		this.logger = new Logger();
+
+		this.logger.info("========================================");
+		this.logger.info("Starting Taleem Server Kernel");
+		this.logger.info("========================================");
+
+		try {
+
+			// --------------------------------------------------
+			// Core
+			// --------------------------------------------------
+
+			this.config = this.initialize("Config", () => new Config());
+
+			this.db = this.initialize("Prisma", () => new PrismaClient());
+
+			this.auth = this.initialize("Auth", () => new Auth(this));
+
+			this.communicationPolicy =
+				this.initialize(
+					"CommunicationPolicy",
+					() => new CommunicationPolicy(this)
+				);
+
+			// --------------------------------------------------
+			// Modules
+			// --------------------------------------------------
+this.user = this.initialize("User", () => new User(this));
+this.admin = this.initialize("Admin", () => new Admin(this));
+this.library = this.initialize("Library", () => new Library(this));
+this.course = this.initialize("Course", () => new Course(this));
+this.image = this.initialize("Image", () => new Image(this));
+this.audio = this.initialize("Audio", () => new Audio(this));
+this.svg = this.initialize("Svg", () => new Svg(this));
+this.communication = this.initialize("Communication", () => new Communication(this));
+this.subscription = this.initialize("Subscription", () => new Subscription(this));
+
+this.logger.info("Server Kernel started successfully.");
+
+		}
+		catch (error) {
+
+			this.logger.error(error.message);
+
+			throw error;
+
+		}
+
+	}
+
+	initialize(name, factory) {
+
+		this.logger.info(`Initializing ${name}...`);
+
+		try {
+
+			const instance = factory();
+
+			this.logger.info(`${name} initialized.`);
+
+			return instance;
+
+		}
+		catch (error) {
+
+			throw new Error(
+				[
+					"",
+					"========================================",
+					"SERVER KERNEL INITIALIZATION FAILED",
+					"----------------------------------------",
+					`Component : ${name}`,
+					`Reason    : ${error.message}`,
+					"",
+					"Server Kernel startup aborted.",
+					"========================================"
+				].join("\n")
+			);
+
+		}
+
+	}
+
+	async shutdown() {
+
+		this.logger.info("Shutting down Server Kernel...");
+
+		try {
+
+			await this.db.$disconnect();
+
+			this.logger.info("Database disconnected.");
+
+			this.logger.info("Server Kernel shutdown complete.");
+
+		}
+		catch (error) {
+
+			throw new Error(
+				[
+					"",
+					"========================================",
+					"SERVER KERNEL SHUTDOWN FAILED",
+					"----------------------------------------",
+					`Reason : ${error.message}`,
+					"========================================"
+				].join("\n")
+			);
+
+		}
+
+	}
+
+}
+
+const kernel = new ServerKernel();
+
+export default kernel;