docs(architecture): add architectural decisions and system diagrams for project overview

Author: tyronejosee

docs/architecture/decisions.md

@@ -0,0 +1,32 @@
+# Architectural Decisions
+
+## Why Next.js App Router?
+
+- Enables hybrid rendering (SSR, SSG, CSR)
+- File-system routing simplifies maintainability
+- Built-in support for middleware (e.g., auth handling)
+
+## Why Supabase?
+
+- Fully managed PostgreSQL with realtime and Row Level Security (RLS)
+- First-class support for OAuth providers (GitHub, Google)
+- Minimal backend maintenance overhead
+- Strong TypeScript support
+
+## Why OAuth only?
+
+- Simplifies user onboarding (no passwords)
+- Leveraging trusted identity providers reduces liability
+- Fits the developer audience of the app
+
+## Session Strategy
+
+- Supabase manages the session via client SDK
+- Session is synced on both client and server (via cookies or `getServerSession`)
+- Supabase middleware or protected layout ensures guards on restricted pages
+
+## Deployment Strategy
+
+- Use GitHub Actions for CI checks (lint, test)
+- Preview deploys on Vercel for PR validation
+- Main branch auto-deploys to production on merge

docs/architecture/diagrams.md

@@ -0,0 +1,52 @@
+# System Diagrams
+
+## Application Architecture
+
+```mermaid
+graph TD
+  A[Public Visitor] --> B[Next.js App Router]
+  C[Authenticated User] --> D[Supabase Auth]
+  D --> E[Session JWT]
+  E --> B
+  B --> F[React Views]
+  B --> G[Supabase Client SDK]
+  G --> H[PostgreSQL]
+  F --> H
+```
+
+> This app supports both unauthenticated public users and authenticated contributors. All content is readable without login. Auth is only required for contributing or interacting (likes, comments, etc.).
+
+---
+
+## Deployment Pipeline
+
+```mermaid
+graph LR
+  A[Push to GitHub] --> B[GitHub Actions CI]
+  B --> C[Vercel Preview Deployment]
+  C --> D[Production Promotion]
+```
+
+> Every push triggers CI checks and Vercel preview deployments for branch validation. Merging into `main` promotes to production automatically.
+
+---
+
+## Authentication Flow
+
+```mermaid
+sequenceDiagram
+  participant Visitor as Public Visitor
+  participant User as Authenticated User
+  participant Supabase
+  participant App
+
+  Visitor->>App: Access public page
+  App-->>Visitor: Load public content
+
+  User->>Supabase: Sign in with GitHub/Google
+  Supabase-->>User: JWT session token
+  User->>App: Load protected UI (Create, Edit, Interact)
+  App->>Supabase: Fetch user data via JWT session
+```
+
+> Only authenticated users can create, edit or remove content. Public visitors remain anonymous but can navigate and view everything.

docs/architecture/overview.md

@@ -0,0 +1,22 @@
+# Architecture Overview
+
+This application is a full-stack web platform built with **Next.js (App Router)** for the frontend and **Supabase** for backend services such as authentication, database, and storage.
+
+## Core Technologies
+
+- **Next.js (App Router)** — Server-side rendering and routing
+- **Supabase** — PostgreSQL DB, Auth (GitHub & Google), Realtime, Storage
+- **TypeScript** — Static typing
+- **Tailwind CSS** — Utility-first styling
+- **Lucide Icons** — UI iconography
+- **GitHub Actions** — CI/CD
+- **Vercel** — Hosting platform
+
+### High-Level Flow
+
+1. User lands on the app via a public route (e.g., `/`)
+2. If unauthenticated, user is redirected to the sign-in page
+3. Auth handled via Supabase (OAuth with GitHub/Google)
+4. Once authenticated, user session is stored via Supabase client and SSR-safe methods
+5. App loads user-specific data using Supabase client/server SDK
+6. Frontend interacts directly with Supabase via client APIs