First commit

doc/ARCHITECTURE.MD

@@ -0,0 +1,68 @@
+# Backend Architecture
+
+This document outlines the architecture of the backend for nwiki. The backend is
+a stateless HTTP API that manages articles, posts, tags, and authenticated user
+access. It uses OAuth 2.0 for authentication and a SQL database for persistent
+storage. No file system is used.
+
+## Main Entry Point
+The backend is initialized from a single entry point that configures the HTTP 
+router, applies middleware, and registers domain-specific route groups. 
+All business logic is organized under domain packages and exposed through a 
+RESTful interface.
+
+## Middleware
+Middleware functions are applied globally or scoped to specific route groups. 
+They operate in sequence to process requests before reaching route handlers.
+
+### Middleware Components
+
+- **Authentication**  
+  Verifies OAuth 2.0 bearer tokens and associates requests with authenticated 
+  users. Required for all operations that involve data creation, modification,
+  or deletion.
+
+- **CORS**  
+  Adds cross-origin headers to support browser-based clients.
+
+- **Logging**  
+  Logs request method, route, status code, and execution time for observability.
+
+- **Error Handling**  
+  Normalizes internal errors into structured JSON responses.
+
+## API Domains
+The backend groups its endpoints into logical domains, each with distinct 
+responsibilities.
+
+### Articles
+Represents content metadata and serves as the logical container for a topic or 
+document. Articles do not store the content body directly.  Articles are used
+for indexing, access control enforcement, and cross-tag navigation.
+
+### Posts
+Implements versioning for article content. Each post represents a version of the
+article body in Markdown and is tied to both an article and the author of the 
+version. Multiple posts may exist per article, forming a history of revisions.
+
+Posts are immutable after creation and store:
+
+### Tags
+Tags are lightweight descriptors used to categorize articles. Tags support
+filtering and navigation across the platform. They are stored in a normalized
+table and can be linked to multiple articles entities.
+
+## Request Lifecycle
+1. The client sends an HTTP request, optionally including an OAuth token.
+2. Middleware validates the request and injects user context if authenticated.
+3. The request is routed to a domain handler based on HTTP method and path.
+4. Business logic processes the request, interacting with the SQL database.
+5. A structured JSON response is returned to the client.
+
+## Design Principles
+- **Statelessness**: All client context is passed with each request via tokens.
+- **Modularity**: API logic is organized by content domain and kept isolated.
+- **Security**: All write operations require valid OAuth authentication.
+- **Scalability**: Stateless design supports horizontal scaling.
+- **Portability**: No file system dependencies; suitable for containerized\ 
+environments.