# amelioro/ameliorate architecture

> Architecture diagram of the GitHub repository amelioro/ameliorate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amelioro/ameliorate
- Repository: https://github.com/amelioro/ameliorate

## Overview

##### Project type and purpose
- This is a full-stack, collaborative problem-analysis web application built on Next.js.

##### File structure
- Top-level “src” contains:
- src/pages – Next.js page components (SSR/SSG routes and API routes)
- src/api – tRPC routers and server-side logic
- src/db – Prisma schema, migrations, and data-migration scripts
- src/common – Domain models and shared utilities used by both frontend and backend
- src/web – Rich client code (React components) organized by feature: comment, topic, view, tutorial, etc.
- Additional directories:
- mock-auth – a Docker-based Auth0 emulator for local development
- e2e – Playwright tests, Dockerfile, and helper scripts for end-to-end testing
- docs-site – static documentation site built with Next.js and MDX
- Config and scripts:
- Netlify and GitHub Actions for CI/CD
- Database-migration and seed scripts under “scripts”
- linters, formatters, and Husky hooks for code quality

##### README for technical stack
- Frontend: Next.js, React, React Flow (diagramming), Zustand (state), React Query, React Hook Form, Tailwind, MUI
- Backend: Next.js API routes with tRPC, Prisma ORM, Neon (Postgres), Auth0, Sentry
- Testing: Vitest for unit/API tests, Playwright for e2e tests

##### Main components
a. Users & Client (Browser)
- Next.js pages for marketing, tutorial, and app routes
- Zustand stores, React Query for data fetching, React Flow for rendering graphs
b. API Server
- Next.js API routes (src/pages/api) and tRPC router (src/api/routers)
- Context layer (initAuth0, Prisma client instantiation)
- Domain logic services under src/api and src/common
c. Database Layer
- Prisma client (basePrisma & extendedPrisma)
- Migrations and data-migration scripts in src/db/migrations and src/db/dataMigrations
- Neon-hosted Postgres cluster
d. Authentication & Authorization
- Auth0 external service in production
- mock-auth Docker service for local development
e. External Services
- Sentry for error tracking and performance monitoring
- Netlify for static and serverless deployment
- GitHub Actions for CI (lint, test, build, smoke tests)

##### Relationships and data flow
- The browser issues HTTP/HTTPS requests to Next.js pages and API routes.
- The client also uses a tRPC client (over HTTP) to invoke typed endpoints.
- tRPC handlers authenticate via Auth0 tokens, then read/update data via Prisma.
- Prisma translates calls to SQL against the Postgres database.
- Real-time collaboration updates flow through tRPC or background webhooks/long-polling as needed.
- Notifications (in-app and e-mail) are triggered by backend logic and queued or sent via an SMTP service.

##### Architectural patterns and principles
- Layered architecture: UI → API → Domain → Persistence
- Monorepo approach: shared code under src/common used on both client and server
- Type-safe contracts end-to-end via TypeScript and tRPC
- Feature-based modularization in src/web (comment, topic, view, tutorial)
- Infrastructure as code: migration scripts and Docker configurations captured in the repo

##### Detail without overthinking
- Shared “common” library used by both client and server.
- Migration pipeline (scripts → Prisma → DB) so newcomers see schema evolution.
- Don’t omit docs-site – treat it as a separate Next.js frontend connected to the GitHub-sourced MDX content and deployed on Netlify.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Client Layer
  subgraph "Client (Browser)" 
    direction TB
    Pages["Next.js Pages"]:::frontend
    click Pages "https://github.com/amelioro/ameliorate/tree/main/src/pages"
    DynamicTopic["Dynamic Topic Page"]:::frontend
    click DynamicTopic "https://github.com/amelioro/ameliorate/blob/main/src/pages/[username]/[topicTitle].page.tsx"
    AuthPages["Auth Pages"]:::frontend
    click AuthPages "https://github.com/amelioro/ameliorate/blob/main/src/pages/api/auth/[...auth0].page.ts"
    TutorialModule["Tutorial Module"]:::frontend
    click TutorialModule "https://github.com/amelioro/ameliorate/tree/main/src/web/tutorial"
    CommentModule["Comment Module"]:::frontend
    click CommentModule "https://github.com/amelioro/ameliorate/tree/main/src/web/comment"
    TopicModule["Topic Module"]:::frontend
    click TopicModule "https://github.com/amelioro/ameliorate/tree/main/src/web/topic"
    ViewModule["View Module"]:::frontend
    click ViewModule "https://github.com/amelioro/ameliorate/tree/main/src/web/view"
    SharedCommon["Shared Common Library"]:::shared
    click SharedCommon "https://github.com/amelioro/ameliorate/tree/main/src/common"
  end

  %% Server Layer
  subgraph "Server (Next.js API & tRPC)"
    direction TB
    API_Routes["Next.js API Routes"]:::backend
    click API_Routes "https://github.com/amelioro/ameliorate/tree/main/src/pages/api"
    TRPC_Routes["tRPC Routers"]:::backend
    click TRPC_Routes "https://github.com/amelioro/ameliorate/blob/main/src/api/routers/_app.ts"
    click TRPC_Routes "https://github.com/amelioro/ameliorate/blob/main/src/api/routers/*.ts"
    ContextAuth["Context & Auth0 Init"]:::backend
    click ContextAuth "https://github.com/amelioro/ameliorate/blob/main/src/api/context.ts"
    click ContextAuth "https://github.com/amelioro/ameliorate/blob/main/src/api/initAuth0.ts"
    DomainLogic["Domain Logic & Notifications"]:::backend
    click DomainLogic "https://github.com/amelioro/ameliorate/tree/main/src/api/topic"
    click DomainLogic "https://github.com/amelioro/ameliorate/blob/main/src/api/email.ts"
    click DomainLogic "https://github.com/amelioro/ameliorate/tree/main/src/api/notifications"
  end

  %% Persistence Layer
  subgraph "Database Layer"
    direction TB
    PrismaBase["Prisma Client Setup"]:::db
    click PrismaBase "https://github.com/amelioro/ameliorate/blob/main/src/db/basePrisma.ts"
    PrismaExt["Extended Prisma Client"]:::db
    click PrismaExt "https://github.com/amelioro/ameliorate/blob/main/src/db/extendedPrisma.ts"
    Migrations["Migrations"]:::db
    click Migrations "https://github.com/amelioro/ameliorate/tree/main/src/db/migrations"
    DataMigrations["Data‐Migration Scripts"]:::db
    click DataMigrations "https://github.com/amelioro/ameliorate/tree/main/src/db/dataMigrations"
    Postgres["Neon Postgres"]:::dbService
  end

  %% External Services
  subgraph "External Services"
    direction TB
    Auth0["Auth0"]:::external
    Sentry["Sentry"]:::external
    Netlify["Netlify"]:::external
    GitHubActions["GitHub Actions"]:::external
    click GitHubActions "https://github.com/amelioro/ameliorate/blob/main/.github/workflows/ci.yml"
    click GitHubActions "https://github.com/amelioro/ameliorate/blob/main/.github/workflows/daily-smoke-tests.yml"
  end

  %% Documentation Site
  subgraph "Documentation"
    DocsSite["Docs Site (Next.js MDX)"]:::frontend
    click DocsSite "https://github.com/amelioro/ameliorate/tree/main/docs-site"
    click DocsSite "https://github.com/amelioro/ameliorate/blob/main/docs-site/netlify.toml"
  end

  %% Dev & Testing
  subgraph "Development & Testing"
    direction TB
    MockAuth["Mock Auth0 Emulator"]:::dev
    click MockAuth "https://github.com/amelioro/ameliorate/tree/main/mock-auth"
    E2E["Playwright E2E Tests"]:::dev
    click E2E "https://github.com/amelioro/ameliorate/tree/main/e2e"
    Scripts["Project Scripts"]:::dev
    click Scripts "https://github.com/amelioro/ameliorate/tree/main/scripts"
    HuskyHooks["Husky & Linting Hooks"]:::dev
    click HuskyHooks "https://github.com/amelioro/ameliorate/blob/main/.husky"
    click HuskyHooks "https://github.com/amelioro/ameliorate/blob/main/.lintstagedrc"
    click HuskyHooks "https://github.com/amelioro/ameliorate/blob/main/.eslintrc.json"
    click HuskyHooks "https://github.com/amelioro/ameliorate/blob/main/.prettierrc"
    Styles["Global Styles & Tailwind"]:::frontend
    click Styles "https://github.com/amelioro/ameliorate/blob/main/src/web/common/globals.css"
    click Styles "https://github.com/amelioro/ameliorate/blob/main/tailwind.config.js"
  end

  %% Flows
  Pages -->|"HTTP(S)"| API_Routes
  DynamicTopic -->|"HTTP(S)"| API_Routes
  AuthPages -->|"HTTP(S)"| API_Routes
  TutorialModule -->|"tRPC/HTTP" | TRPC_Routes
  CommentModule -->|"tRPC/HTTP" | TRPC_Routes
  TopicModule -->|"tRPC/HTTP" | TRPC_Routes
  ViewModule -->|"tRPC/HTTP" | TRPC_Routes
  SharedCommon --> API_Routes
  SharedCommon --> TRPC_Routes

  API_Routes -->|"uses context"| ContextAuth
  TRPC_Routes -->|"uses context"| ContextAuth
  ContextAuth --> Auth0
  API_Routes --> DomainLogic
  TRPC_Routes --> DomainLogic
  DomainLogic --> PrismaBase
  PrismaBase --> PrismaExt
  PrismaExt --> Postgres
  DomainLogic -->|"send errors"| Sentry
  API_Routes -->|"log metrics"| Sentry
  DomainLogic -->|"queue emails"| SMTP[(SMTP Service)]:::external
  SMTP -->|"deliver via"| Auth0
  Scripts --> Migrations
  Scripts --> DataMigrations
  Migrations --> PrismaBase
  DataMigrations --> PrismaBase
  GitHubActions --> Pages
  GitHubActions --> DocsSite
  GitHubActions --> E2E
  Netlify --> Pages
  Netlify --> DocsSite
  MockAuth --> API_Routes
  E2E --> Pages
  E2E --> API_Routes

  %% Styles
  classDef frontend fill:#e0f7e9,stroke:#2e7d32,color:#2e7d32
  classDef backend fill:#e3f2fd,stroke:#1976d2,color:#1976d2
  classDef db fill:#fff3e0,stroke:#ef6c00,color:#e65100
  classDef dbService fill:#ffe0b2,stroke:#fb8c00,color:#e65100
  classDef external fill:#eeeeee,stroke:#9e9e9e,color:#424242
  classDef dev fill:#f3e5f5,stroke:#8e24aa,color:#6a1b9a
  classDef shared fill:#f0f4c3,stroke:#9e9d24,color:#827717
```
