Portfolio Nexus — The Homopedia Nexus

Table of Contents

• The Challenge
• Architecture & Solution
• Monorepo Structure
• Tech Stack
• Key Engineering Decisions
• API Security Model
• Frontend Design System
• CI/CD Pipeline
• Deployment Topology

The Challenge

Most developer portfolios are static HTML pages or Notion exports — they show what you built but not *how* you build. The goal was to make the portfolio itself a living demonstration of engineering capability: a fully deployed, production-grade system with real security, real observability, and a real public API.

Requirements:

• Public portfolio website with premium aesthetics — not a Tailwind template clone
• Private admin panel for moderating public-submitted suggestions
• Secure REST API with JWT auth, CSRF protection, and rate limiting
• Full CI/CD pipeline with quality gates on every PR
• Single codebase, multiple deployable apps, shared type contracts

Architecture & Solution

Portfolio Nexus is a pnpm monorepo with three fully independent applications sharing TypeScript contracts through workspace packages.

Monorepo Structure

portfolio-nexus/
├── apps/
│   ├── website/          # Next.js 14 App Router — Public portfolio
│   ├── admin/            # Vite + React SPA — Private suggestion moderation
│   └── api/              # Express.js Modular Monolith
│
├── packages/
│   ├── types/            # Shared TypeScript contracts (single source of truth)
│   ├── content/          # Markdown case studies, blog posts, project metadata
│   └── config/           # Spider-web scores, project status configs
│
├── infra/                # Dockerfiles + docker-compose.prod.yml (Traefik)
├── .github/workflows/    # CI quality gate
└── *.sh                  # setup, start, stop, dev, deploy scripts

Boundary enforcement: apps/* cannot import from other apps/*. All shared contracts flow through packages/* only. Enforced by ESLint boundaries plugin in CI.

Tech Stack

Key Engineering Decisions

1. SSG + ISR over Full SSR

The portfolio content (case studies, blog posts) is static by nature. Next.js App Router Server Components read markdown files from packages/content/ at build time using fs.readFileSync — zero runtime API cost, maximum Lighthouse scores, instant page loads globally from Vercel CDN.

Only dynamic content (GitHub contribution heatmap) uses ISR with a 1-hour revalidation window.

2. No TailwindCSS — CSS Modules + Design Tokens

The decision to use CSS Modules with CSS custom properties (not Tailwind) means:

• The portfolio looks like no other portfolio (custom, not a template)
• Zero utility class sprawl in JSX
• Design tokens are a single source of truth in tokens.css
• prefers-reduced-motion and dark mode handled cleanly at the CSS layer

3. API Modular Monolith

The API follows the same modular monolith pattern as Aatmanova — each domain lives in a vertical slice that passes the deletion test. Clean architecture layers are enforced:

Router (Express-only) → Controller (parse/respond) → Service (orchestrate)
→ Policy (pure rules, no I/O) → Repository (data only) → Prisma

No circular dependencies enforced by madge in CI.

4. CSRF Double-Submit Pattern

Admin routes use two independent CSRF defenses simultaneously:

• SameSite=Strict cookie — browser won't send cookie on cross-origin requests
• X-Admin-Origin: portfolio-admin custom header — cannot be set by cross-origin forms, only JavaScript (which must already be on the same origin)

Together these make CSRF attacks impossible without compromising the admin origin itself.

5. Manual DI Container

No magic, no decorators, no IoC framework. The entire dependency graph is visible in one file:

// container.ts — readable dependency wiring
const suggestionsRepo   = new SuggestionsRepository(prisma);
const suggestionsPolicy = new SuggestionsPolicy();
const suggestionsService = new SuggestionsService(
  suggestionsRepo, suggestionsPolicy, emailService, logger
);
export const container = {
  suggestionsController: new SuggestionsController(suggestionsService),
};

API Security Model

Frontend Design System

The public website implements the Linear/Vercel aesthetic — dark canvas, precision borders, accent glow — built entirely from scratch with CSS custom properties:

:root {
  --color-background:  #0A0A0A;  /* True black canvas */
  --color-surface:     #111111;  /* Card background */
  --color-accent:      #3B82F6;  /* Blue — primary CTAs */
  --color-text:        #FAFAFA;  /* Near-white primary */
  --color-text-muted:  #A3A3A3;  /* Secondary copy */
  --font-display: 'Plus Jakarta Sans', system-ui, sans-serif;
  --font-body:    'DM Sans', system-ui, sans-serif;
  --font-mono:    'Fira Code', 'Courier New', monospace;
}

Animation rules (from Framer Motion centralized config):

• Entrance: fadeUp (0–24px, opacity 0→1, 0.6s spring easing)
• Hero: Aurora mesh gradient (conic-gradient, hue-rotate CSS animation)
• Hover: translateY(-2px) + glow box-shadow, 200ms
• useReducedMotion() disables all JS animations for accessibility

WCAG AA compliance on all text — targeting AAA 7:1 for body copy in dark mode.

CI/CD Pipeline

GitHub Actions runs on every PR to main or develop:

# quality.yml — runs on every PR
steps:
  - TypeScript: pnpm -r tsc --noEmit           # All workspaces
  - Lint:       pnpm -r lint
  - Tests:      pnpm --filter api test:unit
  - Circular:   npx madge --circular apps/api/src
  - Build:      pnpm --filter website build    # Validates SSG
  - Build:      pnpm --filter admin build
  - Audit:      npm audit --audit-level=high

No merge to main without all checks green.

Deployment Topology

Vercel (Next.js SSG — public website)
  ├── Global CDN edge nodes
  ├── Automatic builds on git push
  └── ISR for GitHub heatmap (1h TTL)

VPS (Ubuntu 22.04)
  ├── Traefik (reverse proxy + Let's Encrypt)
  │   ├── api-portfolio.aatmanova.in → portfolio-api container (port 4000)
  │   └── access.aatmanova.in → Nginx serving Vite admin build
  ├── PM2 (Express API process management)
  │   ├── 1 instance, fork mode
  │   ├── max_memory_restart: 512M
  │   └── zero-downtime: pm2 reload --update-env
  └── PostgreSQL 16 (Docker container, no exposed ports)

Deploy to VPS with a single command:

./deploy.sh "feat: add project case study"
# → Tests → git push → rsync → Docker rebuild → migration → health check