Added documentation

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

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

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*.

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

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.

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

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.