Shiham Ahamed — Portfolio Platform

A production-grade, full-stack personal portfolio monorepo — a public Next.js site, a protected admin CMS, and an Express/MongoDB API, all built from a single npm workspace.

Live site: shiham-ahamed-portfolio.vercel.app · Repo: theShihamAhamed/shiham-ahamed-portfolio

Table of contents

• Overview
• Features
• Tech stack
• Architecture
• Monorepo layout
• Getting started
• Environment variables
• Available scripts
• Testing and quality gates
• Deployment
• Engineering documentation
• Roadmap
• Author
• License

Overview

This repository is not a static template — it's a small full-stack system built to run a real personal portfolio. Content (projects, certifications, achievements, in-progress work, site settings) lives in MongoDB and is managed entirely through a custom-built admin dashboard, so the public site never needs seed data, hard-coded content, or a redeploy to update.

The workspace is split into three applications and two internal packages that share a single dependency graph and lockfile:

Built by Shiham Ahamed, a Software Engineering undergraduate at the Sri Lanka Institute of Information Technology (SLIIT), as the platform behind his personal site and as a demonstration of production-style engineering practice: architecture decision records, a CI-enforced release gate, a documented deployment runbook, and a dependency security review.

Features

Public site (apps/frontend)

• Hero, quick intro, skills & tools, featured projects, "currently building," and contact sections, all driven by CMS content
• Project catalog with filtering plus a detail page per project, rendering sanitized GitHub-flavored Markdown case studies (react-markdown + remark-gfm + rehype-sanitize)
• About page with education, certifications, and achievements
• Contact form with email delivery via Resend
• Dark/light theme (next-themes), motion/microinteractions (Framer Motion), and shadcn/ui + Radix primitives
• SEO by default: dynamic metadata, sitemap.ts, robots.ts, and JSON-LD structured data (Person / WebSite)
• ISR with tag-based, on-demand cache revalidation triggered automatically by admin mutations

Admin dashboard (apps/admin-frontend)

• Cookie-based JWT login backed by the API (no direct database access from the browser)
• Full CRUD for projects, certifications, achievements, and "currently building" entries
• Drag-and-drop reordering (@dnd-kit), rich forms with validation (react-hook-form + zod), and data fetching/caching via @tanstack/react-query
• Image/file uploads routed through the backend to ImageKit

Backend API (apps/backend)

• Access + refresh JWT authentication with hashed passwords (bcryptjs) and DB-tracked admin sessions
• Ownership boundary: the backend is the only writer to MongoDB; both frontends only ever read
• helmet security headers, exact-origin cors, and express-rate-limit on sensitive routes
• multer + image-size upload validation with a configurable size ceiling, proxied to ImageKit
• Zod-validated request/response contracts shared with both frontends via @portfolio/shared
• Signed webhook call to the public frontend's revalidation route after every content mutation

Tech stack

Architecture

The core design decision (see ADR-001) is that public reads bypass the backend entirely. The public frontend reads MongoDB directly from server-side Next.js code, so visitors never wait on Render's free-tier cold starts. The Express API is reserved for everything that mutates data.

flowchart LR
    Visitor(("Site visitor"))
    Admin(("Admin\n(Shiham)"))

    subgraph Vercel
        FE["Public Frontend\nNext.js · apps/frontend"]
        ADMIN["Admin Dashboard\nNext.js · apps/admin-frontend"]
    end

    subgraph Render
        API["Backend API\nExpress · apps/backend"]
    end

    Mongo[("MongoDB Atlas")]
    ImageKit[["ImageKit\n(media storage)"]]
    Resend[["Resend\n(transactional email)"]]

    Visitor -- HTTPS --> FE
    FE -- "server-side reads" --> Mongo
    FE -- "contact form" --> Resend

    Admin -- "login + CRUD" --> ADMIN
    ADMIN -- "REST + cookies" --> API
    API -- "writes" --> Mongo
    API -- "uploads" --> ImageKit
    API -- "signed revalidation webhook" --> FE

Package boundaries are enforced by custom lint scripts (scripts/check-package-boundaries.mjs, scripts/check-frontend-client-boundaries.mjs) rather than convention alone:

flowchart TB
    SHARED["@portfolio/shared\nbrowser-safe types, Zod schemas, slugs, cache tags"]
    DB["@portfolio/db\nserver-only Mongoose models & connection"]

    FE[apps/frontend]
    ADMIN[apps/admin-frontend]
    BE[apps/backend]

    SHARED --> FE
    SHARED --> ADMIN
    SHARED --> BE
    DB --> BE
    DB -. "server-only modules under lib/server/ only" .-> FE

@portfolio/db is never imported by the admin frontend or by any client component — only by the backend, and by explicitly server-only modules in the public frontend.

Monorepo layout

apps/
  frontend/         Public portfolio (Next.js) — reads MongoDB server-side
  admin-frontend/    Protected admin dashboard (Next.js) — talks to the API only
  backend/           Express API — auth, CRUD, uploads, cache revalidation
packages/
  shared/            Browser-safe contracts, Zod schemas, slugs, cache tags
  db/                Server-only Mongoose models and connection handling
docs/                Architecture decisions, deployment guide, release/security records
scripts/             Workspace boundary checks, release-candidate and deployment gates
render.yaml          Render service definition for the backend

Getting started

Prerequisites

• Node.js 20+
• npm (the repo uses npm workspaces and a single root lockfile — don't use yarn/pnpm)
• A MongoDB connection string (Atlas or local)
• Optional for full functionality: an ImageKit account (uploads) and a Resend API key (contact form)

Install

Always install from the repository root so every workspace resolves against the one root lockfile:

git clone https://github.com/theShihamAhamed/shiham-ahamed-portfolio.git
cd shiham-ahamed-portfolio
npm install

Configure environment variables

Copy each app's example file and fill in local values (never commit the resulting .env* files):

cp apps/frontend/.env.example apps/frontend/.env.local
cp apps/admin-frontend/.env.example apps/admin-frontend/.env.local
cp apps/backend/.env.example apps/backend/.env

See Environment variables below for what each value does.

Run an app

Each app builds its internal package dependencies before starting:

npm run dev:frontend   # public site      → http://localhost:3000
npm run dev:admin      # admin dashboard  → http://localhost:3001
npm run dev:backend    # API server       → http://localhost:5000

There is intentionally no seed script — the public frontend renders its real empty/loading/error states until content is created through the admin dashboard.

Environment variables

Only variable names are listed; real values (connection strings, secrets, keys) belong in local, uncommitted env files only.

apps/frontend

apps/admin-frontend

apps/backend

Full annotated examples live in each app's .env.example file.

Available scripts

Run from the repository root:

Testing and quality gates

The workspace ships 29 test files across both packages and all three apps (node:test, run via tsx), covering contract/schema validation, cache-tag invalidation, upload handling, cache revalidation, and UI-behavior contracts (project filtering, project detail rendering, SEO metadata, and more).

npm run validate is the same gate enforced in CI (.github/workflows/ci.yml) on every push and pull request to main: install → lint → typecheck → test → asset check → deployment-config check → release-candidate check → build. scripts/check-release-candidate.mjs additionally verifies that required source files exist, are tracked by git, and aren't accidentally ignored — a lightweight guard against a broken or incomplete release.

Deployment

The system is designed to run across three providers, chosen deliberately so a sleeping free-tier API never blocks public traffic (see ADR-001):

• Public frontend → Vercel, root directory apps/frontend
• Admin frontend → Vercel, root directory apps/admin-frontend (a separate project from the same repo)
• Backend API → Render, defined in render.yaml, health-checked at /api/health/ready
• Data / media / email → MongoDB Atlas, ImageKit, Resend

The full, step-by-step provider setup — environment variables, exact-origin CORS, cookie modes, health checks, and rollback — is documented in docs/deployment-guide.md. It intentionally documents the process without performing a live deployment or provisioning external accounts on its own.

Engineering documentation

Beyond the code, the repository keeps a written record of why things are built the way they are:

Roadmap

Current learning/build focus, reflected on the live "Currently Building" section:

• React Native + Expo, extending the full-stack experience into cross-platform mobile
• Redux and Redux Toolkit for predictable frontend state management
• Migrating from provider subdomains (*.vercel.app, *.onrender.com) to custom domains once ready

Author

Shiham Ahamed — Software Engineering undergraduate at the Sri Lanka Institute of Information Technology (SLIIT), building full-stack applications, backend APIs, and cloud-aware systems. Open to internships, collaborations, and software engineering opportunities.

• Portfolio: shiham-ahamed-portfolio.vercel.app
• GitHub: @theShihamAhamed
• LinkedIn: in/theshihamahamed
• Email: theshihamahamed@gmail.com

License

No open-source license is included. The source is public for portfolio, learning, and reference purposes — © 2026 Shiham Ahamed. All rights reserved. If you'd like to reuse a substantial part of this code, please reach out first.