nwiki-doc/doc/ARCHITECTURE.MD

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.