From 0ecac6533c1342956bc994da996d81bf00bada77 Mon Sep 17 00:00:00 2001
From: Altair-sh <altairgyg@gmail.com>
Date: Fri, 4 Sep 2026 19:36:12 +0200
Subject: [PATCH] added comments

---
 src/app/api/proxy/functions.ts                |  8 ++---
 src/app/api/proxy/paths.ts                    |  2 ++
 .../saveParserBackend/[[...path]]/route.ts    |  2 ++
 src/app/browse/page.tsx                       |  7 +++--
 src/app/layout.tsx                            |  2 ++
 src/app/login/page.tsx                        |  4 +++
 src/app/register/page.tsx                     |  3 ++
 src/components/FormError.tsx                  |  3 +-
 src/components/Navbar.tsx                     |  1 +
 src/components/SaveFileUploadingDialog.tsx    |  6 ++++
 src/config/AppConfig.ts                       |  1 +
 src/instrumentation.ts                        |  7 +++--
 src/lib/configLoader.ts                       |  4 +++
 src/lib/customConsoleLog.ts                   | 11 ++++---
 src/lib/myFonts.ts                            |  3 ++
 src/services/AuthService.ts                   |  3 ++
 src/services/SaveParserBackendService.ts      | 30 +++++++++----------
 17 files changed, 68 insertions(+), 29 deletions(-)

diff --git a/src/app/api/proxy/functions.ts b/src/app/api/proxy/functions.ts
index 7c2b6a3..eb1b493 100644
--- a/src/app/api/proxy/functions.ts
+++ b/src/app/api/proxy/functions.ts
@@ -38,8 +38,8 @@ export async function redirectRequest(
     })
 }
 
-/// Browsers send OPTIONS request sometimes to check webserver allowed headers and methods.
-/// My backend doesn't support such requests so use proxy to answer to it that all headers and methods are allowed
+/// Browsers send OPTIONS request sometimes to check webserver's allowed headers and methods.
+/// My C# backend doesn't support OPTIONS, so the proxy answer to OPTIONS request that all headers and methods are allowed.
 export async function responseToOPTIONS(req: NextRequest): Promise<NextResponse> {
     // console.log('proxy responding to CORS OPTIONS', req.url)
 
@@ -48,8 +48,8 @@ export async function responseToOPTIONS(req: NextRequest): Promise<NextResponse>
         headers: {
             'Access-Control-Allow-Origin': '*',
             'Access-Control-Allow-Methods': 'GET, POST, PUT, PATCH, DELETE, HEAD',
-            'Access-Control-Allow-Headers':
-                req.headers.get('access-control-request-headers') || 'Content-Type, Authorization',
+            'Access-Control-Allow-Headers': '*',
+            // req.headers.get('access-control-request-headers') || 'Content-Type, Authorization'
         },
     })
 }
diff --git a/src/app/api/proxy/paths.ts b/src/app/api/proxy/paths.ts
index 621c063..a80924b 100644
--- a/src/app/api/proxy/paths.ts
+++ b/src/app/api/proxy/paths.ts
@@ -1,3 +1,5 @@
+// Directories in src/api/proxy/ are routes.
+// Their paths are stored here to simplify refactoring.
 export const PROXY_PATHS = {
     saveParserBackend: '/api/proxy/saveParserBackend',
 }
diff --git a/src/app/api/proxy/saveParserBackend/[[...path]]/route.ts b/src/app/api/proxy/saveParserBackend/[[...path]]/route.ts
index 4ff91e3..0f4a432 100644
--- a/src/app/api/proxy/saveParserBackend/[[...path]]/route.ts
+++ b/src/app/api/proxy/saveParserBackend/[[...path]]/route.ts
@@ -4,10 +4,12 @@ import { redirectRequest, responseToOPTIONS as respondToOPTIONS } from '@/app/ap
 import { PROXY_PATHS } from '@/app/api/proxy/paths'
 import { appConfig } from '@/lib/configLoader'
 
+// Forwards the incoming request to the save parser backend.
 async function redirect(req: NextRequest): Promise<NextResponse> {
     return await redirectRequest(req, PROXY_PATHS.saveParserBackend, appConfig.services.saveParserBackend.url)
 }
 
+// handlers for each request method on this route
 export const GET = redirect
 export const POST = redirect
 export const PUT = redirect
diff --git a/src/app/browse/page.tsx b/src/app/browse/page.tsx
index 4c29877..534575b 100644
--- a/src/app/browse/page.tsx
+++ b/src/app/browse/page.tsx
@@ -1,15 +1,16 @@
 'use client'
 
 import { AgGridReact } from 'ag-grid-react'
-import { AllCommunityModule, themeQuartz } from 'ag-grid-community'
+import { AllCommunityModule, themeQuartz, colorSchemeDark } from 'ag-grid-community'
 import { useState, useEffect } from 'react'
-import { colorSchemeDark } from 'ag-grid-community'
 
 // TODO: create tabs with general info, tables, plots
 
-export default function BrowsePage() {
+// Page that shows a save file's parsed data in a grid.
+export default function BrowseSaveDataPage() {
     const [agTheme, setAgTheme] = useState(themeQuartz)
 
+    // Keep the grid theme in sync with the browser's light/dark color scheme.
     useEffect(() => {
         const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
         setAgTheme(prefersDark ? themeQuartz.withPart(colorSchemeDark) : themeQuartz)
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index 0f94fe8..444228a 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -8,7 +8,9 @@ export const metadata: Metadata = {
     title: 'Home',
 }
 
+// Root layout wrapping every page with the navbar and shared styles.
 export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
+    // Register the ag-grid community features
     ModuleRegistry.registerModules([AllCommunityModule])
     return (
         <html lang="en">
diff --git a/src/app/login/page.tsx b/src/app/login/page.tsx
index 5330d63..dc48961 100644
--- a/src/app/login/page.tsx
+++ b/src/app/login/page.tsx
@@ -4,6 +4,7 @@ import { useState } from 'react'
 import { authService } from '@/services/AuthService'
 import FormError from '@/components/FormError'
 
+// Page with the login form.
 export default function LoginPage() {
     const [formData, setFormData] = useState({
         email: '',
@@ -13,14 +14,17 @@ export default function LoginPage() {
 
     const [error, setError] = useState<string | null>(null)
 
+    // Update the form data with new field value 
     const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
         const { name, value, type, checked } = e.target
         setFormData((prev) => ({
             ...prev,
+            // checkboxes store value in property "checked"
             [name]: type === 'checkbox' ? checked : value,
         }))
     }
 
+    // Submit the form data to the auth service or show an error on failure.
     const handleSubmit = async (e: React.FormEvent) => {
         e.preventDefault()
         setError(null)
diff --git a/src/app/register/page.tsx b/src/app/register/page.tsx
index f81c109..5d91360 100644
--- a/src/app/register/page.tsx
+++ b/src/app/register/page.tsx
@@ -5,6 +5,7 @@ import { useRouter } from 'next/navigation'
 import { authService } from '@/services/AuthService'
 import FormError from '@/components/FormError'
 
+// Page with the registration form.
 export default function RegisterPage() {
     const router = useRouter()
 
@@ -17,6 +18,7 @@ export default function RegisterPage() {
 
     const [error, setError] = useState<string | null>(null)
 
+    // Update the matching form field by input name.
     const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
         setFormData((prev) => ({
             ...prev,
@@ -24,6 +26,7 @@ export default function RegisterPage() {
         }))
     }
 
+    // Validate the passwords match, register the user, then redirect to login.
     const handleSubmit = async (e: React.FormEvent) => {
         e.preventDefault()
         setError(null)
diff --git a/src/components/FormError.tsx b/src/components/FormError.tsx
index 1becbf9..4f16dc6 100644
--- a/src/components/FormError.tsx
+++ b/src/components/FormError.tsx
@@ -2,8 +2,9 @@ interface FormErrorProps {
     message: string | null
 }
 
+// Shows a red alert box with an error message, or nothing if there is no message.
 export default function FormError(props: FormErrorProps) {
-    if (!props.message || props.message === '') return null
+    if (!props.message) return null
 
     return (
         <div className="alert alert-danger" role="alert">
diff --git a/src/components/Navbar.tsx b/src/components/Navbar.tsx
index c6acb70..af9c9f3 100644
--- a/src/components/Navbar.tsx
+++ b/src/components/Navbar.tsx
@@ -3,6 +3,7 @@
 import Link from 'next/link'
 import { font_Hack } from '@/lib/myFonts'
 
+// Top navigation bar with a home link and login/register buttons.
 export default function Navbar() {
     return (
         <nav className={`navbar navbar-expand-lg navbar-dark bg-dark px-3 ${font_Hack.className}`}>
diff --git a/src/components/SaveFileUploadingDialog.tsx b/src/components/SaveFileUploadingDialog.tsx
index 1201dcd..4845ac6 100644
--- a/src/components/SaveFileUploadingDialog.tsx
+++ b/src/components/SaveFileUploadingDialog.tsx
@@ -12,6 +12,7 @@ export enum GameEnum {
 //TODO: move to separate page
 //TODO: add redirect to ?id={id} to see status of long parsing save
 
+// Dialog for picking a game and save file, uploading it, and polling the parse status until done.
 export default function SaveFileUploadingDialog() {
     const [error, setError] = useState<string | null>(null)
     const [selectedFile, setSelectedFile] = useState<File | null>(null)
@@ -20,16 +21,19 @@ export default function SaveFileUploadingDialog() {
     const [saveStatus, setSaveStatus] = useState<SaveStatusResponse | null>(null)
     const [uploadResult, setUploadResult] = useState<UploadSaveResponse | null>(null)
 
+    // Update the selected game from the dropdown.
     const handleGameSelect = (e: React.ChangeEvent<HTMLSelectElement>) => {
         setGame(e.target.value as GameEnum)
     }
 
+    // Store the file chosen in the file picker.
     const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
         if (e.target.files && e.target.files[0]) {
             setSelectedFile(e.target.files[0])
         }
     }
 
+    // Uploads the selected save file, then repeatedly polls its status until parsing is done or an error occurs.
     const handleUpload = async (e: React.FormEvent) => {
         e.preventDefault()
         setError(null)
@@ -43,6 +47,7 @@ export default function SaveFileUploadingDialog() {
             setUploadResult(uploadResponse)
 
             const pollInterval = 1000 // ms
+            // Poll the backend every second for the parsing status until it reports "done".
             const intervalId = setInterval(async () => {
                 try {
                     const statusResponse = await saveParserBackendService.getSaveStatus(uploadResponse.id)
@@ -66,6 +71,7 @@ export default function SaveFileUploadingDialog() {
         }
     }
 
+    // Build the <option> list from the GameEnum values.
     const gameEnumOptions = Object.values(GameEnum).map((value) => (
         <option key={value} value={value}>
             {value}
diff --git a/src/config/AppConfig.ts b/src/config/AppConfig.ts
index 250c02f..94f6b31 100644
--- a/src/config/AppConfig.ts
+++ b/src/config/AppConfig.ts
@@ -1,4 +1,5 @@
 'server'
+// Default app configuration, values can be overrided in runtimeConfig.json
 export const defaultConfig = {
     services: {
         saveParserBackend: {
diff --git a/src/instrumentation.ts b/src/instrumentation.ts
index a501364..bdc2266 100644
--- a/src/instrumentation.ts
+++ b/src/instrumentation.ts
@@ -1,5 +1,8 @@
-import '@/lib/customConsoleLog'
+// imports for both server and client go here
 
-export function register() {
+// run once when the server starts.
+export async function register() {
     console.log('hello from instrumentation.ts!')
+    await import('@/lib/customConsoleLog') // replaces console.log
+    await import('@/lib/configLoader') // forces loadConfig() to run at server startup
 }
diff --git a/src/lib/configLoader.ts b/src/lib/configLoader.ts
index eb43749..a4cccfa 100644
--- a/src/lib/configLoader.ts
+++ b/src/lib/configLoader.ts
@@ -5,14 +5,17 @@ import { AppConfig, defaultConfig } from '@/config/AppConfig'
 
 const configFilePath = path.join(process.cwd(), 'runtimeConfig.json')
 
+// Reads runtimeConfig.json (merging it over the defaults) and creates new config file if missing
 function loadConfig(): AppConfig {
     let config = defaultConfig
 
     if (fs.existsSync(configFilePath)) {
+        console.log(`reading config file '${configFilePath}'`)
         const raw = fs.readFileSync(configFilePath, 'utf-8')
         const parsed = JSON.parse(raw)
         config = { ...defaultConfig, ...parsed }
     } else {
+        console.log(`creating default config file '${configFilePath}'`)
         fs.mkdirSync(path.dirname(configFilePath), { recursive: true })
     }
     fs.writeFileSync(configFilePath, JSON.stringify(defaultConfig, null, 4))
@@ -20,4 +23,5 @@ function loadConfig(): AppConfig {
     return config
 }
 
+// Run once at first file import
 export const appConfig = loadConfig()
diff --git a/src/lib/customConsoleLog.ts b/src/lib/customConsoleLog.ts
index f696c99..2c98619 100644
--- a/src/lib/customConsoleLog.ts
+++ b/src/lib/customConsoleLog.ts
@@ -1,13 +1,16 @@
-let _custom_console_log_injected = false
-if (!_custom_console_log_injected) {
-    _custom_console_log_injected = true
+// Replaces console.log with a version that prefixes a timestamp
+function injectConsoleLog() {
     const originalLog = console.log
 
     function customLog(message?: any, ...optionalParams: any[]) {
         const now = new Date()
         const timestamp = now.toTimeString().split(' ')[0] // hh:mm:ss
-        originalLog(`[${timestamp}] ${message}`, ...optionalParams, ':3')
+        originalLog(`[${timestamp}] ${message}`, ...optionalParams)
     }
 
     console.log = customLog
+    return null
 }
+
+// Run once at first file import
+export const _inject_run_once = injectConsoleLog()
diff --git a/src/lib/myFonts.ts b/src/lib/myFonts.ts
index 8830392..83b8f05 100644
--- a/src/lib/myFonts.ts
+++ b/src/lib/myFonts.ts
@@ -1,6 +1,8 @@
 import localFont from 'next/font/local'
 import { IBM_Plex_Sans } from 'next/font/google'
 
+// Loads the Google-hosted IBM Plex Sans font.
+// It is downloaded to build directory during build.
 export const font_IbmPlexSans = IBM_Plex_Sans({
     subsets: ['latin'],
     weight: ['400', '500', '700'],
@@ -8,6 +10,7 @@ export const font_IbmPlexSans = IBM_Plex_Sans({
     variable: '--font-ibm-plex-sans',
 })
 
+// Loads the local Hack font used by the navbar.
 export const font_Hack = localFont({
     src: [
         {
diff --git a/src/services/AuthService.ts b/src/services/AuthService.ts
index dc3adc0..c1703f6 100644
--- a/src/services/AuthService.ts
+++ b/src/services/AuthService.ts
@@ -3,11 +3,13 @@
 class AuthService {
     private API_BASE = '/api/auth'
 
+    // Hashes the password before sending it to the backend
     private hashPassword(password: string) {
         // TODO: password hashing
         return password
     }
 
+    // Logs in with email and password, returning the parsed JSON response.
     async login(email: string, password: string) {
         const response = await fetch(`${this.API_BASE}/login`, {
             method: 'POST',
@@ -25,6 +27,7 @@ class AuthService {
         return await response.json()
     }
 
+    // Registers a new user, returning the parsed JSON response.
     async register(name: string, email: string, password: string) {
         const response = await fetch(`${this.API_BASE}/register`, {
             method: 'POST',
diff --git a/src/services/SaveParserBackendService.ts b/src/services/SaveParserBackendService.ts
index 879ec26..c1aa862 100644
--- a/src/services/SaveParserBackendService.ts
+++ b/src/services/SaveParserBackendService.ts
@@ -11,18 +11,20 @@ export interface SaveStatusResponse {
     uploadDateTime: string
 }
 
+// Tries to read  the response body as string, returning an empty string if that fails.
+async function getBodyTextOrEmpty(res: Response): Promise<string> {
+    try {
+        return await res.text()
+    } catch {
+        return ''
+    }
+}
+
 export class SaveParserBackendService {
     private API_BASE = PROXY_PATHS.saveParserBackend
 
-    private async tryGetResponseJson(res: Response): Promise<string> {
-        try {
-            const body = await res.json()
-            return JSON.stringify(body)
-        } catch {}
-        return ''
-    }
-
     //TODO: save size limit 30 mb
+    // Uploads a save file for the given game and returns its assigned id.
     async uploadSave(game: string, file: File): Promise<UploadSaveResponse> {
         const url = `${this.API_BASE}/uploadSave?game=${encodeURIComponent(game)}`
         const response = await fetch(url, {
@@ -34,33 +36,31 @@ export class SaveParserBackendService {
         })
 
         if (!response.ok) {
-            throw new Error(`Failed to upload save: ${response.statusText} ${await this.tryGetResponseJson(response)}`)
+            throw new Error(`Failed to upload save: ${response.statusText} ` + (await getBodyTextOrEmpty(response)))
         }
 
         return await response.json()
     }
 
+    // Fetches the current parsing status of a previously uploaded save.
     async getSaveStatus(id: string): Promise<SaveStatusResponse> {
         const url = `${this.API_BASE}/getSaveStatus?id=${encodeURIComponent(id)}`
         const response = await fetch(url)
 
         if (!response.ok) {
-            throw new Error(
-                `Failed to get save status: ${response.statusText} ${await this.tryGetResponseJson(response)}`
-            )
+            throw new Error(`Failed to get save status: ${response.statusText} ` + (await getBodyTextOrEmpty(response)))
         }
 
         return await response.json()
     }
 
+    // Fetches the fully parsed data for a save once its parsing is done.
     async getParsedSave(id: string): Promise<Record<string, any>> {
         const url = `${this.API_BASE}/getParsedSave?id=${encodeURIComponent(id)}`
         const response = await fetch(url)
 
         if (!response.ok) {
-            throw new Error(
-                `Failed to get parsed save: ${response.statusText} ${await this.tryGetResponseJson(response)}`
-            )
+            throw new Error(`Failed to get parsed save: ${response.statusText} ` + (await getBodyTextOrEmpty(response)))
         }
 
         return await response.json()