How amelioro/ameliorate works
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.