🌐 Weekend Project: Build a Full-Stack Social Media App

The Goal

Build something that behaves like a real social product, not a tutorial demo. You open Pulse, register, and land on a feed. You write a post, optionally attach a photo, and hit publish — the post appears instantly while its image quietly finishes processing in the background. You scroll a feed that loads fast even under repeated refreshes because it's cached. You like someone's post and, on their screen, a notification badge ticks up in real time — no refresh, no polling. That whole experience is Week 10's toolbox working together.

Every lesson this week was a single tool. This weekend you learn the harder skill: composition. The emphasis below is deliberately on how the pieces connect — the request flows, the boundaries, the contracts — rather than re-typing every line you already wrote in the week's lessons. When a stage needs a pattern you built earlier (a Mongoose model, a CORS block, a Socket.IO handler), we reference it and show the seam where it plugs in.

System Architecture

Before any code, hold the whole system in your head. Two apps you build (the React client and the Express API) sit alongside three backing services (MongoDB, Redis, and a queue worker). The client only ever talks to the API; the API orchestrates everything behind it.

Notice that Redis plays two roles — it's both the cache and the queue's backing store — which is common and efficient. Notice too that the worker is its own process: it shares the database and Redis but runs separately, so a spike in image jobs never slows the API that's serving the feed. Those two observations are the heart of the design.

Prerequisites

This is the Week 10 capstone, so it leans on the whole week plus Week 9's auth. You don't need to have finished every lesson perfectly, but you should recognize each of these — the stages assume the pattern and show only the integration seam:

You'll need Node.js 18+, a MongoDB (local or Atlas), and a Redis instance. The fastest way to get Mongo and Redis locally is Docker:

# Two throwaway containers — perfect for a weekend build
docker run -d --name pulse-mongo -p 27017:27017 mongo:7
docker run -d --name pulse-redis -p 6379:6379 redis:7

Required Features Checklist

These are the non-negotiables — each one is a Week 10 skill, and each must actually connect to the others. Tick them off as they come online.

Project Structure

A monorepo with two clearly separated apps. The server/ keeps the role-based layout from Week 8 and adds folders for the new concerns — cache/, queue/, and realtime/. The client/ is the Vite/React shape from Week 5 with an api/ layer as the single door to the backend.

pulse/
├── package.json            <-- root: dev script runs both apps
├── docker-compose.yml      <-- optional: mongo + redis
├── client/                 <-- Vite + React front end
│   ├── package.json
│   ├── .env                <-- VITE_API_URL=http://localhost:4000
│   └── src/
│       ├── main.jsx
│       ├── api/
│       │   ├── client.js       <-- axios instance + JWT interceptor
│       │   └── posts.js        <-- feed/create/like/comment calls
│       ├── context/AuthContext.jsx
│       ├── hooks/useSocket.js  <-- connects Socket.IO with the token
│       ├── pages/{Login,Feed,Profile}.jsx
│       └── components/{PostCard,NewPost,NotificationsBell}.jsx
└── server/                 <-- Express API + worker
    ├── package.json
    ├── .env                <-- MONGO_URI, REDIS_URL, JWT_SECRET, CLIENT_URL
    └── src/
        ├── server.js           <-- connect DB+Redis, create http+socket, listen
        ├── app.js              <-- express app: cors, json, routes, errors
        ├── config/{db,redis}.js
        ├── models/{User,Post}.js
        ├── middleware/{auth,upload,errorHandler}.js
        ├── routes/{auth,posts}.js
        ├── controllers/{authController,postController}.js
        ├── cache/postCache.js  <-- get/set/invalidate helpers
        ├── queue/imageQueue.js  <-- BullMQ producer (enqueue jobs)
        ├── worker.js           <-- BullMQ consumer (separate process)
        └── realtime/io.js      <-- Socket.IO setup + notifyUser()

Stage 1 — Scaffold the Monorepo & CORS

Create the two apps and get them talking across the origin boundary — the very first integration problem. The client runs on Vite's port (5173), the API on 4000. Those are different origins, so the browser will block the API call unless the server explicitly allows it.

mkdir pulse && cd pulse

# Front end
npm create vite@latest client -- --template react
cd client && npm install && npm install axios socket.io-client && cd ..

# Back end
mkdir server && cd server && npm init -y
npm install express cors mongoose dotenv bcrypt jsonwebtoken \
  multer sharp ioredis bullmq socket.io
npm install --save-dev nodemon
cd ..

The API's job in this stage is to build the Express app with a tight CORS policy. Don't reflexively allow every origin — name the client origin from an env var, and only allow it. This is the exact pattern from the CORS lesson, dropped into the app factory:

// server/src/app.js — build the app (no listen here)
const express = require('express');
const cors = require('cors');
const authRoutes = require('./routes/auth');
const postRoutes = require('./routes/posts');
const { notFound, errorHandler } = require('./middleware/errorHandler');

function createApp() {
  const app = express();

  // CORS: allow ONLY the client origin, and the Authorization header.
  app.use(cors({
    origin: process.env.CLIENT_URL,          // e.g. http://localhost:5173
    methods: ['GET', 'POST', 'PATCH', 'DELETE'],
    allowedHeaders: ['Content-Type', 'Authorization'],
  }));

  app.use(express.json());
  app.use('/uploads', express.static('uploads')); // serve processed images

  app.use('/api/auth', authRoutes);
  app.use('/api/posts', postRoutes);

  app.use(notFound);       // 404 for unmatched routes
  app.use(errorHandler);   // the one 4-arg handler, mounted last
  return app;
}

module.exports = createApp;

Stage 2 — Auth & the API Client

Auth is the spine everything else hangs on. You already built the pieces in Week 9 — hash on register, sign a JWT on login, verify it in middleware. Here we focus on the seam: how the client stores that token and re-attaches it to every request without you remembering to.

The verify middleware (server)

One middleware turns a valid Authorization: Bearer <token> header into req.userId. Every write route mounts it; every controller downstream can trust that id.

// server/src/middleware/auth.js
const jwt = require('jsonwebtoken');

module.exports = function requireAuth(req, res, next) {
  const header = req.headers.authorization || '';
  const token = header.startsWith('Bearer ') ? header.slice(7) : null;
  if (!token) return res.status(401).json({ error: 'Authentication required' });

  try {
    const payload = jwt.verify(token, process.env.JWT_SECRET);
    req.userId = payload.sub;   // the user id we signed at login
    next();
  } catch {
    return res.status(401).json({ error: 'Invalid or expired token' });
  }
};

The API client (front end) — one door, one interceptor

This is the single most important front-end file for integration. Instead of scattering fetch calls and copy-pasting the token everywhere, you create one axios instance with the base URL baked in and an interceptor that attaches the JWT automatically. Every feature calls through this door.

// client/src/api/client.js
import axios from 'axios';

export const api = axios.create({
  baseURL: import.meta.env.VITE_API_URL, // http://localhost:4000
});

// Attach the token to every outgoing request.
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('token');
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

// Normalize errors and auto-logout on a 401.
api.interceptors.response.use(
  (res) => res,
  (err) => {
    if (err.response?.status === 401) {
      localStorage.removeItem('token');
      window.location.assign('/login');
    }
    return Promise.reject(err);
  }
);

With that in place a feature module is tiny — it never thinks about tokens or base URLs again:

// client/src/api/posts.js
import { api } from './client';

export const getFeed = (page = 1) =>
  api.get(`/api/posts?page=${page}`).then((r) => r.data);

export const createPost = (formData) =>
  api.post('/api/posts', formData).then((r) => r.data); // FormData → multipart

export const likePost = (id) =>
  api.post(`/api/posts/${id}/like`).then((r) => r.data);

Stage 3 — The Posts Feed (CRUD)

Now the core resource. A Post belongs to a user, carries text and an optional image, and tracks likes and comments — the same Mongoose modeling you did in Week 8, so here's just the shape and the seams that matter for later stages (the image field the worker fills in, the author the socket notifies).

// server/src/models/Post.js
const mongoose = require('mongoose');

const postSchema = new mongoose.Schema({
  author: { type: mongoose.Schema.Types.ObjectId, ref: 'User', required: true },
  text:   { type: String, required: true, trim: true, maxlength: 500 },
  // Filled in by the background worker once the resize finishes:
  image:  { url: String, status: { type: String, default: 'none' } }, // none|processing|ready
  likes:  [{ type: mongoose.Schema.Types.ObjectId, ref: 'User' }],
  comments: [{
    author: { type: mongoose.Schema.Types.ObjectId, ref: 'User' },
    text:   { type: String, required: true, maxlength: 300 },
    createdAt: { type: Date, default: Date.now },
  }],
}, { timestamps: true });

module.exports = mongoose.model('Post', postSchema);

The route table maps REST verbs to controllers, with the auth middleware guarding every write. Reads are public here; locking them down is a stretch goal.

// server/src/routes/posts.js
const router = require('express').Router();
const c = require('../controllers/postController');
const requireAuth = require('../middleware/auth');
const upload = require('../middleware/upload'); // Multer (Stage 5)

router.get('/', c.list);                                   // GET  /api/posts (cached)
router.get('/:id', c.getOne);                              // GET  /api/posts/:id
router.post('/', requireAuth, upload.single('image'), c.create); // POST (multipart)
router.patch('/:id', requireAuth, c.update);               // PATCH /api/posts/:id
router.delete('/:id', requireAuth, c.remove);              // DELETE /api/posts/:id
router.post('/:id/like', requireAuth, c.like);             // POST like → notifies author
router.post('/:id/comments', requireAuth, c.comment);      // POST comment → notifies author

module.exports = router;

The "Touches" column is the integration map in miniature: notice how many routes have to bust the cache and how the interaction routes notify over the socket. Those cross-cutting concerns are exactly what the next three stages wire in — and why doing them after plain CRUD works keeps each addition testable.

Stage 4 — Redis Cache on the Feed

The feed is your hottest endpoint — hit on every page load and refresh — and it runs the same Mongo query over and over. This is the textbook case for cache-aside: check Redis first; on a miss, query Mongo and store the result with a short TTL; return. The payoff is real only if you also handle the hard half — invalidation — so a new or edited post never serves stale.

Keep the cache logic in one small helper so the controller stays readable and the key scheme lives in exactly one place:

// server/src/cache/postCache.js
const redis = require('../config/redis'); // an ioredis client
const TTL_SECONDS = 60;

const feedKey = (page) => `feed:page:${page}`;

exports.getFeed = async (page) => {
  const hit = await redis.get(feedKey(page));
  return hit ? JSON.parse(hit) : null;
};

exports.setFeed = (page, data) =>
  redis.set(feedKey(page), JSON.stringify(data), 'EX', TTL_SECONDS);

// Any write to posts calls this. Wipe every feed page in one shot.
exports.invalidateFeed = async () => {
  const keys = await redis.keys('feed:page:*');
  if (keys.length) await redis.del(keys);
};

The controller becomes a clean cache-aside read, and — critically — every write calls invalidateFeed():

// server/src/controllers/postController.js (excerpt)
const Post = require('../models/Post');
const cache = require('../cache/postCache');
const asyncHandler = require('../middleware/asyncHandler');

exports.list = asyncHandler(async (req, res) => {
  const page = Math.max(1, parseInt(req.query.page, 10) || 1);

  const cached = await cache.getFeed(page);       // 1. try cache
  if (cached) return res.json({ ...cached, cached: true });

  const limit = 10;                               // 2. miss → hit Mongo
  const posts = await Post.find()
    .sort({ createdAt: -1 })
    .skip((page - 1) * limit).limit(limit)
    .populate('author', 'username avatar');

  const payload = { data: posts, page };
  await cache.setFeed(page, payload);             // 3. warm the cache
  res.json({ ...payload, cached: false });
});

exports.create = asyncHandler(async (req, res) => {
  const post = await Post.create({ author: req.userId, text: req.body.text });
  await cache.invalidateFeed();                   // write ⇒ bust the cache
  // ...enqueue image job (Stage 5) then respond 201
  res.status(201).json({ data: post });
});

The cached: true|false flag in the response is a deliberate teaching aid — hit the feed twice and watch it flip, then create a post and watch it flip back. That's your invalidation working, made visible.

Stage 5 — Image Upload + Background Job

Uploads are where the "do the slow thing later" lesson pays off. Resizing an image with sharp can take hundreds of milliseconds — far too long to make the user wait inside the request. So the request does only the fast part (accept the file, enqueue a job, respond) and a separate worker does the slow part. The post is created immediately with image.status: 'processing', and the worker flips it to 'ready' when done.

Multer, configured as reusable middleware, accepts the file and enforces limits at the edge:

// server/src/middleware/upload.js
const multer = require('multer');

module.exports = multer({
  storage: multer.diskStorage({
    destination: 'uploads/tmp',
    filename: (req, file, cb) => cb(null, `${Date.now()}-${file.originalname}`),
  }),
  limits: { fileSize: 5 * 1024 * 1024 },   // 5 MB cap
  fileFilter: (req, file, cb) =>
    cb(null, /^image\/(png|jpe?g|webp)$/.test(file.mimetype)),
});

The producer is a BullMQ queue — the create controller adds a job and moves on. It never waits for the resize:

// server/src/queue/imageQueue.js
const { Queue } = require('bullmq');
const connection = { url: process.env.REDIS_URL };

const imageQueue = new Queue('image-processing', { connection });

// Called from the create controller after multer runs:
exports.enqueueResize = (postId, tmpPath) =>
  imageQueue.add('resize', { postId, tmpPath }, {
    attempts: 3,                              // retry a few times on failure
    backoff: { type: 'exponential', delay: 1000 },
    removeOnComplete: true,
  });
module.exports.imageQueue = imageQueue;

The worker is the separate process. It pulls jobs, resizes with sharp, saves the output, and updates the post — the moment it flips status to ready, the next feed load shows the image:

// server/src/worker.js — run with: node src/worker.js
require('dotenv').config();
const { Worker } = require('bullmq');
const sharp = require('sharp');
const path = require('path');
const connectDB = require('./config/db');
const Post = require('./models/Post');
const cache = require('./cache/postCache');

async function start() {
  await connectDB();
  const connection = { url: process.env.REDIS_URL };

  new Worker('image-processing', async (job) => {
    const { postId, tmpPath } = job.data;
    const outName = `${postId}.webp`;
    const outPath = path.join('uploads', outName);

    await sharp(tmpPath).resize(1080, 1080, { fit: 'inside' })
      .webp({ quality: 80 }).toFile(outPath);   // the slow part, off the request

    await Post.findByIdAndUpdate(postId, {
      image: { url: `/uploads/${outName}`, status: 'ready' },
    });
    await cache.invalidateFeed();               // fresh image ⇒ bust the feed
    console.log(`Processed image for post ${postId}`);
  }, { connection });

  console.log('Image worker ready, waiting for jobs...');
}
start();

Stage 6 — Real-Time Notifications

The last connective tissue: when someone likes or comments on your post, you should know instantly. Polling is wasteful; this is what Socket.IO is for. The key integration idea is rooms — each logged-in user joins a private room named after their id, so the server can push to one specific person rather than broadcasting to everyone.

Set up the Socket.IO server alongside Express, sharing the same HTTP server, and authenticate the socket with the same JWT the REST API uses — auth is one system, not two:

// server/src/realtime/io.js
const { Server } = require('socket.io');
const jwt = require('jsonwebtoken');

let io;

function initIO(httpServer) {
  io = new Server(httpServer, {
    cors: { origin: process.env.CLIENT_URL, methods: ['GET', 'POST'] },
  });

  // Authenticate the socket handshake with the JWT.
  io.use((socket, next) => {
    try {
      const { token } = socket.handshake.auth;
      const payload = jwt.verify(token, process.env.JWT_SECRET);
      socket.userId = payload.sub;
      next();
    } catch {
      next(new Error('Unauthorized socket'));
    }
  });

  io.on('connection', (socket) => {
    socket.join(socket.userId);   // private room = the user's own id
  });
}

// Called from controllers to push a notification to one user.
function notifyUser(userId, notification) {
  if (io) io.to(String(userId)).emit('notification', notification);
}

module.exports = { initIO, notifyUser };

The like/comment controllers do their normal database work, then call notifyUser with the post's author. That single line is the whole real-time feature from the API's side:

// server/src/controllers/postController.js (like handler)
const { notifyUser } = require('../realtime/io');

exports.like = asyncHandler(async (req, res) => {
  const post = await Post.findById(req.params.id);
  if (!post) return res.status(404).json({ error: 'Post not found' });

  if (!post.likes.includes(req.userId)) post.likes.push(req.userId);
  await post.save();
  await cache.invalidateFeed();

  // Notify the author — but not if they liked their own post.
  if (String(post.author) !== req.userId) {
    notifyUser(post.author, {
      type: 'like', postId: post.id, at: Date.now(),
    });
  }
  res.json({ likes: post.likes.length });
});

On the client, a hook connects the socket with the token and listens. When a notification arrives, the bell updates — no refresh:

// client/src/hooks/useSocket.js
import { useEffect } from 'react';
import { io } from 'socket.io-client';

export function useSocket(onNotification) {
  useEffect(() => {
    const token = localStorage.getItem('token');
    if (!token) return;

    const socket = io(import.meta.env.VITE_API_URL, { auth: { token } });
    socket.on('notification', onNotification);

    return () => socket.disconnect();   // clean up on unmount
  }, [onNotification]);
}

Stage 7 — Run It End to End

Integration only counts when it all runs at once. You now have four things to start: Mongo, Redis (both from Docker in the prerequisites), the API server, and the worker — plus the Vite client. A root script can launch the Node processes together; run the client in its own terminal.

// pulse/package.json (root) — needs: npm i -D concurrently
{
  "scripts": {
    "api":    "nodemon server/src/server.js",
    "worker": "nodemon server/src/worker.js",
    "dev":    "concurrently -n api,worker \"npm:api\" \"npm:worker\""
  }
}

# Terminal 1 — backend (API + worker together)
npm run dev

# Terminal 2 — front end
cd client && npm run dev   # http://localhost:5173

Then walk the integration checklist — each step proves that two systems are talking:

That last one is worth savoring: because the job lives in Redis, killing the worker mid-flight doesn't lose the work — restart it and the job runs. The same durability that makes queues useful in production makes this demo convincing.

Stretch Goals

Cleared the required build with time to spare? Deepen the integration — none of these are needed to pass the rubric, but each strengthens a real-world seam.

Self-Check Rubric

Grade yourself before calling it done. Aim for "yes" across the first two columns; the stretch column is bonus. Because this is an integration project, the rubric weights connections as heavily as features.

Summary

The lasting lesson of this weekend isn't any single technology — it's that a real application is defined by its joints. You saw a write bust a cache, an upload become a queued job, a database change fan out to a socket, and one token unlock both HTTP and WebSocket traffic. Individually these were Week 10 lessons; together they're an architecture. Knowing where the pieces connect, and what has to stay in sync across those seams, is the difference between a developer who can follow a tutorial and one who can design a system.

📚 Additional Resources

• Socket.IO — Rooms
• BullMQ — Queues, workers, and jobs
• Redis — Caching patterns
• sharp — High-performance image processing
• MDN — Cross-Origin Resource Sharing (CORS)
• Express — Error handling

🚀 What's Next?

You just ran five moving parts by hand — Mongo, Redis, an API, a worker, and a client — and felt how fiddly it is to start them in the right order. Week 11 fixes exactly that. It opens with Container concepts: how Docker packages each of these services with its dependencies into a portable image, so "works on my machine" becomes "works everywhere," and docker-compose up replaces your five terminals with one command. Everything you assembled this weekend is about to become something you can ship as a single, reproducible unit.