docs : update

.env.example

@@ -10,11 +10,53 @@ DB_NAME=codestardb
 
 # Spring Boot / JWT
 JWT_SECRET=change_me_use_a_long_random_string_at_least_64_chars
-JWT_EXPIRATION=86400000
+JWT_EXPIRATION=604800000 # one week by default (in milliseconds)
+
+# Signup open (true = No invitation code needed)
+SIGNUP_OPEN=true
+
+# Bootstrap super-admin on first boot.
+# If the email exists in the database with a lower role, it is promoted. The password NEVER overwrites an existing user.
+CODESTAR_BOOTSTRAP_SUPER_ADMIN_EMAIL=example@gmail.com
+CODESTAR_BOOTSTRAP_SUPER_ADMIN_PASSWORD=change_me_to_a_strong_password
+CODESTAR_BOOTSTRAP_SUPER_ADMIN_DISPLAY_NAME=John
 
 # Ports (optional — defaults shown)
 BACKEND_PORT=8080
 FRONTEND_PORT=3000
 
-# Next.js — URL the browser uses to reach the backend API
-NEXT_PUBLIC_API_URL=http://localhost:8080
+# Path to an external branding JSON file (optional) - Leave empty to use the bundled default
+# You can customize the branding either by pointing to an external file OR by editing the bundled one.
+INSTANCE_CONFIG_PATH=
+
+# Frontend
+# Backend & Frontend base URL
+API_URL=http://localhost:8080
+SITE_URL=http://localhost:3000
+# Name of the httpOnly cookie storing the JWT (must match backend + frontend code expectations).
+AUTH_COOKIE_NAME=codestar_token
+
+
+# Media storage (course images) — quotas
+# Reject uploads that would push a single user (or the whole instance) over the cap (HTTP 413).
+MEDIA_USER_QUOTA_MB=100
+MEDIA_INSTANCE_QUOTA_MB=5000
+
+# Media upload rate limit per user (token bucket) — over the limit returns HTTP 429.
+# capacity = burst size; refill = tokens added back per minute.
+MEDIA_RATE_LIMIT_CAPACITY=20
+MEDIA_RATE_LIMIT_REFILL_PER_MINUTE=20
+
+# Spring runtime profile (optional): prod (default) or dev.
+# SPRING_PROFILES_ACTIVE=prod
+
+# AI Course Generator
+AI_API_URL=https://api.groq.com/openai/v1
+AI_API_KEY=
+AI_MODEL=llama-3.3-70b-versatile
+AI_MAX_TOKENS=16384
+AI_TEMPERATURE=0.4
+AI_CONNECT_TIMEOUT_SECONDS=5
+AI_TIMEOUT_SECONDS=90
+AI_RATE_LIMIT_CAPACITY=5
+AI_RATE_LIMIT_REFILL_PER_MINUTE=2

.gitignore

@@ -1,13 +1,80 @@
-# Environment secrets
+# Environment / secrets
 .env
+.env.*
+!.env.example
+*.pem
+*.key
+*.crt
 
 # OS
 .DS_Store
+.AppleDouble
+.LSOverride
+._*
+.Spotlight-V100
+.Trashes
 Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+Desktop.ini
+$RECYCLE.BIN/
+*.lnk
+.fuse_hidden*
+.directory
+.Trash-*
+.nfs*
 
-# IDE
+# IDE / Editors
 .idea/
 *.iml
+*.iws
+*.ipr
+out/
 
-# Claude 
+# VS Code
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+*.code-workspace
+.history/
+
+# Eclipse
+.classpath
+.project
+.settings/
+.metadata/
+.factorypath
+.apt_generated/
+
+# NetBeans
+nbproject/private/
+nbbuild/
+nbdist/
+.nb-gradle/
+
+# Vim / Emacs / Sublime / Misc
+*.swp
+*.swo
+*~
+.*.sw?
+*.sublime-workspace
+*.sublime-project
+.\#*
+\#*\#
+
+# AI assistants / agents
 .claude/
+.aider*
+.cursor/
+
+# Logs / temp
+*.log
+logs/
+tmp/
+temp/
+
+# have to be delete
+codestar-draft-design/

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "i18n-ally.localesPaths": [
+        "apps/frontend/messages"
+    ],
+    "java.configuration.updateBuildConfiguration": "interactive"
+}

README.md

@@ -1,6 +1,6 @@
 # Codestar
 
-Open-source & self-hosted e-learning platform
+Open-source & self-hosted e-learning platform template to build yours easly.
 
 ## Backend 
 

apps/backend/.gitignore

@@ -0,0 +1,41 @@
+# Maven
+target/
+!.mvn/wrapper/maven-wrapper.jar
+!**/src/main/**/target/
+!**/src/test/**/target/
+dependency-reduced-pom.xml
+.flattened-pom.xml
+pom.xml.tag
+pom.xml.releaseBackup
+pom.xml.versionsBackup
+pom.xml.next
+release.properties
+buildNumber.properties
+
+# Gradle (safety net)
+.gradle/
+build/
+!gradle/wrapper/gradle-wrapper.jar
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+# Java
+*.class
+*.jar
+*.war
+*.nar
+*.ear
+*.zip
+*.tar.gz
+*.rar
+*.ctxt
+.mtj.tmp/
+hs_err_pid*
+replay_pid*
+
+# Spring Boot
+HELP.md
+.springBeans
+
+# Logs
+*.log

apps/backend/Dockerfile

@@ -1,4 +1,4 @@
-# Stage 1: Build
+# Build
 FROM maven:3.9-eclipse-temurin-17 AS build
 WORKDIR /app
 
@@ -9,7 +9,7 @@ RUN mvn dependency:go-offline -B
 COPY src ./src
 RUN mvn package -DskipTests -B
 
-# Stage 2: Runtime
+# Runtime
 FROM eclipse-temurin:17-jre-alpine
 WORKDIR /app
 

apps/backend/pom.xml

@@ -14,7 +14,7 @@
 	<artifactId>backend</artifactId>
 	<version>0.0.1-SNAPSHOT</version>
 	<name>backend</name>
-	<description>Demo project for Spring Boot</description>
+	<description>API backend for CodeStar</description>
 
 	<properties>
 		<java.version>17</java.version>
@@ -26,6 +26,11 @@
 			<artifactId>spring-boot-starter-web</artifactId>
 		</dependency>
 
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-starter-actuator</artifactId>
+		</dependency>
+
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-test</artifactId>
@@ -42,12 +47,33 @@
 			<artifactId>spring-boot-starter-data-jpa</artifactId>
 		</dependency>
 
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-starter-validation</artifactId>
+		</dependency>
+
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-configuration-processor</artifactId>
+			<optional>true</optional>
+		</dependency>
+
 		<dependency>
 			<groupId>org.postgresql</groupId>
 			<artifactId>postgresql</artifactId>
 			<scope>runtime</scope>
 		</dependency>
 
+		<dependency>
+			<groupId>org.flywaydb</groupId>
+			<artifactId>flyway-core</artifactId>
+		</dependency>
+
+		<dependency>
+			<groupId>org.flywaydb</groupId>
+			<artifactId>flyway-database-postgresql</artifactId>
+		</dependency>
+
 		<dependency>
 			<groupId>io.jsonwebtoken</groupId>
 			<artifactId>jjwt-api</artifactId>
@@ -71,7 +97,7 @@
 		<dependency>
 			<groupId>org.springdoc</groupId>
 			<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
-			<version>2.5.0</version>
+			<version>2.7.0</version>
 		</dependency>
 
 	</dependencies>

apps/backend/src/main/java/com/codestar/backend/BackendApplication.java

@@ -2,8 +2,12 @@
 
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
+import org.springframework.scheduling.annotation.EnableScheduling;
 
 @SpringBootApplication
+@EnableScheduling
+@ConfigurationPropertiesScan
 public class BackendApplication {
 
 	public static void main(String[] args) {

apps/backend/src/main/java/com/codestar/backend/config/AiProperties.java

@@ -0,0 +1,23 @@
+package com.codestar.backend.config;
+
+import jakarta.validation.constraints.DecimalMax;
+import jakarta.validation.constraints.DecimalMin;
+import jakarta.validation.constraints.Positive;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.validation.annotation.Validated;
+
+@ConfigurationProperties(prefix = "codestar.ai")
+@Validated
+public record AiProperties(
+        String apiUrl,
+        String apiKey,
+        String model,
+        @Positive int maxTokens,
+        @DecimalMin("0.0") @DecimalMax("2.0") double temperature,
+        @Positive int connectTimeoutSeconds,
+        @Positive int timeoutSeconds,
+        @Positive int rateLimitCapacity,
+        @Positive int rateLimitRefillPerMinute,
+        @Positive long rateLimitIdleTtlMinutes,
+        @Positive long rateLimitSweepMs
+) {}

apps/backend/src/main/java/com/codestar/backend/config/BootstrapProperties.java

@@ -0,0 +1,11 @@
+package com.codestar.backend.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.boot.context.properties.bind.DefaultValue;
+
+@ConfigurationProperties(prefix = "codestar.bootstrap.super-admin")
+public record BootstrapProperties(
+        @DefaultValue("") String email,
+        @DefaultValue("") String password,
+        @DefaultValue("Super-admin") String displayName
+) {}

apps/backend/src/main/java/com/codestar/backend/config/CorsProperties.java

@@ -0,0 +1,14 @@
+package com.codestar.backend.config;
+
+import jakarta.validation.constraints.NotEmpty;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.validation.annotation.Validated;
+
+import java.util.List;
+
+
+@ConfigurationProperties(prefix = "codestar.cors")
+@Validated
+public record CorsProperties(
+        @NotEmpty List<String> allowedOrigins
+) {}

apps/backend/src/main/java/com/codestar/backend/config/InstanceProperties.java

@@ -0,0 +1,13 @@
+package com.codestar.backend.config;
+
+import jakarta.validation.constraints.NotBlank;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.validation.annotation.Validated;
+
+
+@ConfigurationProperties(prefix = "codestar.instance")
+@Validated
+public record InstanceProperties(
+        // Path/URL to the branding instance.json file
+        @NotBlank String configPath
+) {}

apps/backend/src/main/java/com/codestar/backend/config/JwtProperties.java

@@ -0,0 +1,14 @@
+package com.codestar.backend.config;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Positive;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.validation.annotation.Validated;
+
+
+@ConfigurationProperties(prefix = "jwt")
+@Validated
+public record JwtProperties(
+        @NotBlank String secret,
+        @Positive long expiration
+) {}

apps/backend/src/main/java/com/codestar/backend/config/MediaProperties.java

@@ -0,0 +1,24 @@
+package com.codestar.backend.config;
+
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Positive;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.validation.annotation.Validated;
+
+
+@ConfigurationProperties(prefix = "codestar.media")
+@Validated
+public record MediaProperties(
+        @NotBlank String storagePath,
+        @Positive long userQuotaMb,
+        @Positive long instanceQuotaMb,
+        @Valid RateLimit rateLimit
+) {
+    public record RateLimit(
+            @Positive int capacity,
+            @Positive int refillPerMinute,
+            @Positive long idleTtlMinutes,
+            @Positive long sweepMs
+    ) {}
+}