From 6b7da583bdf9b482bf8da61a64227391c8899f9e Mon Sep 17 00:00:00 2001
From: Cliff Hill <xlorep@darkhelm.org>
Date: Thu, 18 Sep 2025 21:21:25 -0400
Subject: [PATCH] Updating README.

Signed-off-by: Cliff Hill <xlorep@darkhelm.org>
---
 README.md | 98 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 76 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 96b5d9d7..cfcb5e53 100644
--- a/README.md
+++ b/README.md
@@ -8,28 +8,82 @@ This is a full-stack application simulating an online booking system for confere
 
 ## Design Decisions
 
-- **Backend:**
-  - Uses Python 3.13 for modern syntax and improved debugging.
-  - FastAPI, SQLAlchemy, asyncpg
-  - Follows a modular structure: routers, services, schemas, and models are separated for maintainability.
-  - Dataclasses and type hints improve readability and reliability.
-  - Async SQLAlchemy for scalable database access.
-  - Robust testing with Nox and Pytest.
-- **Frontend:**
-  - React with TypeScript for type safety and maintainability.
-  - Material-UI for a modern, responsive UI.
-  - Centralized logging
-  - Clear separation of concerns.
-- **Containerization:**
-  - Docker Compose for both production and development, with hot-reload and volume mounts for rapid iteration.
-  - Production environment is run with a simple `docker compose up` from the root directory.
-  - Development environment is run with `docker compose -f compose.dev.yml up` from the root directory.
-  - Development compose extends the production compose, allowing for changes in the production compose to be
-    reflected in the development compose as well.
-- **Security:**
-  - No authentication in this demo, but structure allows for easy integration of OpenID/JWT.
-  - Environment variables for secrets; in production, use a secrets manager.
-  - Backend dependencies are validated using `security` and other tests inside `nox`.
+### React Contexts for State Management
+
+- Global state for rooms, bookings, and users via context providers.
+- Real-time updates using SSE in context.
+
+### Modular Component Architecture
+
+- Reusable, focused components (e.g., BookingForm, RoomList, RoomSelect, CalendarView).
+- Shared UI logic abstracted into dedicated components.
+
+### TypeScript for Safety and Documentation
+
+- Strong typing for all props, state, and data models.
+- Centralized type/interface definitions.
+
+### Unified Color and Style Logic
+
+- Room/event colors assigned by room id modulo, using CSS custom properties.
+- Consistent visual theming across lists, dropdowns, and calendar.
+
+### Separation of Concerns
+
+- Business logic and API calls abstracted into helpers and service modules.
+- Thin UI components focused on rendering and interaction.
+
+### Robust Error Handling and Validation
+
+- Field-level validation and user-friendly error messages in forms.
+- Backend errors formatted for clarity.
+
+### Centralized Logging
+
+- Logging utility used throughout frontend and backend for analytics and debugging.
+- Key actions and lifecycle events are logged.
+
+### JSDoc and Docstrings for Documentation
+
+- File-level and component-level documentation in both frontend and backend.
+- TypeScript interfaces and Python models are documented.
+
+### React Router for Navigation
+
+- Page routing and programmatic navigation after booking actions.
+
+### Accessibility and User Experience
+
+- Disabled states, error messages, and skeleton loaders for better UX.
+- Visual distinction for selected/unavailable rooms.
+
+### FastAPI Backend with SQLAlchemy ORM
+
+- Async API endpoints grouped by resource (rooms, bookings, users).
+- Database models with relationships and constraints.
+
+### Pydantic Schemas for Validation
+
+- Separate schemas for create, update, and response objects.
+
+### Service Layer Abstraction in Backend
+
+- Business logic separated from HTTP routing.
+
+### Testing and Code Quality
+
+^ Pytest, coverage, pre-commit hooks, and code style enforcement.
+
+### Docker Compose for Orchestration
+
+- Multi-service setup: backend (FastAPI), frontend (React), and Postgres database.
+- Custom network, healthchecks, and persistent volumes.
+- Environment variables managed via .env files.
+
+### Extensibility and Maintainability
+
+- Modular design for easy feature addition and refactoring.
+- Generated from Hypermodern Python Cookiecutter for best practices.
 
 ### AI Use