From 6652787c117241446605c4c9cef5f40bc3e04967 Mon Sep 17 00:00:00 2001 From: Lukas Morgenstern Date: Sat, 17 Jan 2026 14:45:38 +0100 Subject: [PATCH 1/7] Added api.md to the docs --- docs/packages/api.md | 55 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 docs/packages/api.md diff --git a/docs/packages/api.md b/docs/packages/api.md new file mode 100644 index 0000000..e00e11a --- /dev/null +++ b/docs/packages/api.md @@ -0,0 +1,55 @@ +# API Package + +The API package provides structured access to database-backed data +and encapsulates domain-level data manipulation logic. + +It acts as the primary interface between the database layer and the +server logic. + +## Responsibilities +- Represent database tables and derived views as Java objects +- Provide list-based access to related records where appropriate +- Encapsulate domain-specific data modification logic + (e.g. password changes, state updates) +- Enforce consistency and validation rules close to the data + +## Data Representation + +- Most API classes map to a primary database table +- Some API objects expose related tables as lists or collections + to simplify common access patterns +- These collections represent *conceptual ownership*, not raw SQL joins + +## Data Modification Rules + +- API classes may modify persistent data when the change: + - directly affects the represented entity + - enforces domain-specific invariants +- Examples: + - Setting or validating passwords + - Updating status fields + - Maintaining referential integrity + +- API classes must NOT: + - Implement cross-entity workflows + - Coordinate multiple unrelated domain objects + - Perform request- or session-specific logic + +## Layer Interaction + +- API classes use the sql package for persistence +- Server logic orchestrates API objects but does not modify database + state directly +- Request handlers and commands interact with data exclusively + through the API package + +### Example + +Changing a student's password is implemented in the Student API class, +as it: +- modifies only the Student entity +- enforces password rules +- ensures consistent persistence + +The server layer is responsible only for deciding *when* this happens, +not *how*. From 246bd8837805591780d9f2cf040c6425cff69a3c Mon Sep 17 00:00:00 2001 From: Lukas Morgenstern Date: Sat, 17 Jan 2026 15:26:49 +0100 Subject: [PATCH 2/7] Added server.md to the docs --- docs/packages/server.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 docs/packages/server.md diff --git a/docs/packages/server.md b/docs/packages/server.md new file mode 100644 index 0000000..eac2cfd --- /dev/null +++ b/docs/packages/server.md @@ -0,0 +1,41 @@ +# Server Package + +The server package represents the runtime environment of the +application. + +It contains long-lived core components and subsystems that are +initialized by the Application class and used throughout the +application's lifetime. + + +## Responsibilities +- Hold and expose core runtime components +- Provide shared infrastructure to application subsystems +- Group and structure server-side functionality +- Contain protocol- and domain-specific subsystems +This includes: +- The WebServer instance +- Session management infrastructure +- Database access infrastructure +- Resource access + +## Non-Responsibilities + +The server package does NOT: +- Define application startup or shutdown order +- Parse command-line arguments + +## Subpackages +- webserver: HTTP handling and request/response processing +- sql: database connectivity +- resources: file-based resources +- commands: server-side CLI commands + +## WebServer Class + +The WebServer class represents the concrete HTTP server instance used +by the application. + +Although it closely cooperates with the webserver subpackage, it +resides in the server package because it represents a top-level server +component rather than a low-level HTTP abstraction. From 9d388860b1c2c749ea24d629b5853e20f078953d Mon Sep 17 00:00:00 2001 From: Lukas Morgenstern Date: Sat, 17 Jan 2026 15:27:04 +0100 Subject: [PATCH 3/7] Added toplevel.md to the docs --- docs/packages/toplevel.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 docs/packages/toplevel.md diff --git a/docs/packages/toplevel.md b/docs/packages/toplevel.md new file mode 100644 index 0000000..576fadd --- /dev/null +++ b/docs/packages/toplevel.md @@ -0,0 +1,18 @@ +# Toplevel Package + +## Application (Singleton) +- Entry point for application startup +- Prepares environment +- Initializes core services + +## Registry +Central registration mechanism for: +- Commands +- Request handlers +- Other extensible components + +This enables decoupled registration and extensibility. + +## Arguments +- Argument: single command-line argument +- Arguments: parsed argument collection From 1fb30ead6804fd5d02d9b85e0217c77ff2844935 Mon Sep 17 00:00:00 2001 From: Lukas Morgenstern Date: Sat, 17 Jan 2026 15:27:26 +0100 Subject: [PATCH 4/7] Added webserver.md to the docs --- docs/architecture/webserver.md | 101 +++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 docs/architecture/webserver.md diff --git a/docs/architecture/webserver.md b/docs/architecture/webserver.md new file mode 100644 index 0000000..88ea0a7 --- /dev/null +++ b/docs/architecture/webserver.md @@ -0,0 +1,101 @@ +# Webserver Package + +The webserver package implements a custom HTTP server abstraction. +It translates low-level HTTP requests into structured application +requests and produces corresponding responses. + +## Responsibilities + +- Abstract HTTP request and response handling +- Provide a structured request/response model +- Route requests to appropriate handlers +- Manage HTTP-specific concerns (headers, cookies, status codes) +- Integrate session management into request handling + +## Request Handlers + +Handlers implement request-specific logic. + +- HttpHandler + Base abstraction for all handlers + +- GetRequestHandler + Handles HTTP GET requests + +- PostRequestHandler + Handles HTTP POST requests + +- WebResourceHandler + Handles the mapping of web resource paths to resource locations. + +Handlers are responsible for: +- Interpreting requests +- Validating parameters +- Delegating business logic to the server or API layer + +Handlers must not access the database directly. + +## Request Model + +The request package defines structured representations of incoming +HTTP requests. + +- HttpRequest + Common base abstraction + +- GetRequest / PostRequest + Specialized request types + +- HttpHeader + Used to determine request characteristics + +- RequestType + Enum defining supported request types + +- APIPostRequest + Specialized POST request providing optimized access to API objects + (for example when entity IDs are passed as parameters) + +## Response Model + +The response package defines structured HTTP responses. + +- HttpResponse + Base response abstraction + +- GetResponse / PostResponse + Specialized response types + +- TemplatingPreprocessor + Helper for preparing template-based responses + +## Session Management + +Session handling is integrated into the webserver package. + +- Session + Represents a single user session + +- SessionManager + Manages session lifecycle and access + +- SessionStorage + Defines session persistence and storage strategy + +## Supporting HTTP Types + +The following classes represent HTTP-level concepts and are used +throughout the webserver package: + +- AccessManager / AccessLevel +- ContentType +- Cookie +- Status +- WebPath + +## Design Principles + +- The webserver package is protocol-focused +- It must not contain domain or business logic +- It must remain independent of database details +- All application-specific logic is delegated outward From abe5f99650e7767f1cd05f4c9ea7ba2b9cdb3a12 Mon Sep 17 00:00:00 2001 From: Lukas Morgenstern Date: Sat, 17 Jan 2026 15:32:04 +0100 Subject: [PATCH 5/7] Added startup-lifecycle.md --- docs/architecture/startup-lifecycle.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 docs/architecture/startup-lifecycle.md diff --git a/docs/architecture/startup-lifecycle.md b/docs/architecture/startup-lifecycle.md new file mode 100644 index 0000000..d213f0a --- /dev/null +++ b/docs/architecture/startup-lifecycle.md @@ -0,0 +1,9 @@ +# Application Startup Lifecycle + +1. Application singleton is initialized +2. Command-line arguments are parsed +3. Commands are registered and the command line is set up for commands +4. Database connection is established +5. Holidays data is fetched +6. Modules, Handlers and Web Paths are registered +7. WebServer and SessionManager are started \ No newline at end of file From a92e8b31a6df783ad1b97443d2406d8835741b3d Mon Sep 17 00:00:00 2001 From: Lukas Morgenstern Date: Sat, 17 Jan 2026 15:33:18 +0100 Subject: [PATCH 6/7] Added utils.md --- docs/packages/utils.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/packages/utils.md diff --git a/docs/packages/utils.md b/docs/packages/utils.md new file mode 100644 index 0000000..9f70085 --- /dev/null +++ b/docs/packages/utils.md @@ -0,0 +1,7 @@ +## Utils Package + +Contains small, reusable utilities. + +Rule: +If a utility grows in complexity or domain relevance, it should be +moved into a dedicated package. From 82361178e151e8a532a2827b031d674001a7253c Mon Sep 17 00:00:00 2001 From: Lukas Morgenstern Date: Sat, 17 Jan 2026 15:38:35 +0100 Subject: [PATCH 7/7] Added Holidays.md --- docs/packages/holidays.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 docs/packages/holidays.md diff --git a/docs/packages/holidays.md b/docs/packages/holidays.md new file mode 100644 index 0000000..c2ba589 --- /dev/null +++ b/docs/packages/holidays.md @@ -0,0 +1,21 @@ +# Holidays Package + +The Holidays package is responsible for retrieving and providing +holiday information from an external API. + +## Responsibilities +- Fetch holiday data from a remote endpoint during application startup +- Cache and normalize holiday information +- Provide a stable API for querying holiday data + +## Lifecycle +1. Holiday data is accessed from an API endpoint (using an http client) +2. Current school year is determined +3. Current week and total weeks in this school year is determined +4. This data is passed to the API. + +## Design Rationale +This functionality is isolated due to: +- External dependency +- Increased complexity +- Different failure modes compared to database-backed data \ No newline at end of file