69 lines
2.8 KiB
Markdown
69 lines
2.8 KiB
Markdown
# 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.
|