Reddit Clone — Next.js + GraphQL (StepZen) + NextAuth

A full‑stack Reddit‑style social app showcasing authenticated posting, voting, and commenting across topic‑based communities. The frontend is built with Next.js, TypeScript, Tailwind CSS, and Apollo Client. The backend is a PostgreSQL database exposed via a GraphQL API powered by StepZen. Authentication is handled with NextAuth (Google and Reddit providers).

This project highlights skills in Next.js app architecture, GraphQL data modeling, Apollo Client caching, OAuth flows, and production‑ready UI with Tailwind.

Key Features

• Authentication with OAuth: Google and Reddit sign‑in via NextAuth
• Create/read posts: Title, body, image support, subreddit taxonomy
• Upvotes/downvotes: Vote tally with per‑user vote protection
• Comments: Nested on post detail page with relative timestamps
• Topic feeds: Global feed and filtered feeds by r/{topic}
• Responsive UI: Tailwind CSS, accessible, keyboard focusable controls
• GraphQL backend: StepZen over PostgreSQL (e.g., Supabase)

Tech Stack

• Frontend: Next.js 12+, React 18, TypeScript, Tailwind CSS
• State/Data: Apollo Client 3, GraphQL
• Auth: NextAuth (Google, Reddit providers)
• Backend: StepZen GraphQL (schema stitching + materializers)
• Database: PostgreSQL
• UX: react-hook-form, react-hot-toast, react-timeago, Heroicons

---

Architecture

The app consumes a StepZen GraphQL endpoint that maps to PostgreSQL tables (post, comment, vote, subreddit). Apollo Client manages queries, mutations, and cache updates. NextAuth secures protected actions (creating posts, voting, commenting).

flowchart LR
  Browser[Next.js + Apollo Client] -- Queries/Mutations --> StepZen[StepZen GraphQL API]
  StepZen -- SQL (materializers/dbquery) --> Postgres[(PostgreSQL)]
  Browser -. OAuth .- NextAuth[NextAuth]
  NextAuth -. Providers .- Google[Google OAuth]
  NextAuth -. Providers .- Reddit[Reddit OAuth]

Loading

Notable Implementation Details

• Apollo cache refetch: Mutations refetch getPostList, getPostListByTopic, and getVotesByPostId to keep UI consistent
• Dynamic routes: pages/post/[postId].tsx and pages/subreddit/[topic].tsx
• StepZen schema: Materialized relations (votes, comments, subreddit) resolved via SQL in stepzen/postgresql/postgresql.graphql
• Image optimization: Next/Image domains whitelisted in next.config.js

---

Screens and Flows

• Home feed: Create posts and view top communities
• Subreddit page: Filtered feed by topic; scoped post creation
• Post detail: Vote, comment, and read comment threads
• Auth screen: Provider‑based sign in (Google/Reddit)

---

Project Structure

components/        Reusable UI: Post, Feed, PostBox, Header, Avatar, SubredditRow
graphql/           Apollo Client queries and mutations
pages/             Next.js routes (index, post/[postId], subreddit/[topic], auth)
stepzen/           StepZen SDL and config mapping GraphQL to PostgreSQL
styles/            Tailwind layer utilities
apollo-client.js   ApolloClient configuration

---

Environment Variables

Create a .env.local in the project root:

# StepZen (client reads this to send the API key in Authorization header)
NEXT_PUBLIC_STEPZEN_KEY=your_stepzen_api_key

# NextAuth (OAuth)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
REDDIT_CLIENT_ID=your_reddit_client_id
REDDIT_CLIENT_SECRET=your_reddit_client_secret

# Recommended for NextAuth in production
NEXTAUTH_URL=https://your-deployment-url
NEXTAUTH_SECRET=complex_random_string

StepZen service configuration is under stepzen/. You will supply your own database credentials and StepZen account details locally; do not commit secrets.

---

Getting Started (Local Development)

Prerequisites:

• Node.js 16+
• Yarn (or npm/pnpm)
• StepZen CLI (npm i -g stepzen)
• A PostgreSQL database (e.g., Supabase) with the following tables: post, comment, vote, subreddit

1. Install dependencies

yarn

2. Configure environment

• Create .env.local with the variables above
• Ensure next.config.js image domains match any external images you plan to load

3. Start StepZen (GraphQL API)

cd stepzen
stepzen start
# The CLI will display the endpoint and API key; set NEXT_PUBLIC_STEPZEN_KEY accordingly

4. Run the web app

yarn dev

Open http://localhost:3000

---

GraphQL Overview

The core entities are:

• Post { id, title, body, image, subreddit_id, username, created_at }
• Comment { id, post_id, text, username, created_at }
• Vote { id, post_id, upvote, username, created_at }
• Subreddit { id, topic, created_at }

Queries and mutations are defined in graphql/ (client) and stepzen/postgresql/postgresql.graphql (server SDL). Example operations:

• Queries: getPostList, getPostListByTopic, getPostListByPostId, getVotesByPostId, getSubredditListLimit
• Mutations: insertPost, insertSubreddit, insertVote, insertComment

---

Scripts

yarn dev      # start Next.js in development
yarn build    # build for production
yarn start    # run production build

---

Accessibility & UX Notes

• Semantic, keyboard‑focusable controls with visible states
• Loading states for network requests (Jelly loader)
• Toaster feedback on mutations (create post, comment)

---

Roadmap / Future Improvements

• Optimistic UI updates for votes and comments
• Infinite scrolling and real pagination
• Image upload (e.g., S3/Cloudinary) vs. URL field
• Full test coverage (unit/integration with React Testing Library & Playwright)
• Role‑based moderation tools per subreddit

---

Skills Demonstrated (for recruiters and AI scrapers)

• Next.js, React 18, TypeScript, Tailwind CSS
• Apollo Client 3, GraphQL schema design, cache management
• StepZen GraphQL over PostgreSQL (SQL materializers, SDL)
• NextAuth OAuth (Google, Reddit) and session‑based UI
• Form handling (react‑hook‑form), toasts, timeago UX
• Dynamic routing, API integration, environment configuration

If you have questions about the implementation or want to discuss trade‑offs, feel free to open an issue.