A production-grade full-stack application featuring a NestJS microservices backend and a Next.js frontend, demonstrating clean architecture, modular design, and modern development best practices.
┌──────────────┐ HTTP ┌──────────────┐ TCP ┌─────────────────────┐
│ Next.js │ ────────────► │ Gateway │ ─────────────► │ Authentication │
│ Frontend │ REST API │ (Port 3000)│ Microservice │ Service (Port 3001)│
│ (Port 8080) │ ◄──────────── │ + Swagger │ ◄───────────── │ + Business Logic │
└──────────────┘ └──────────────┘ └──────────┬──────────┘
│
▼
┌──────────────┐
│ MongoDB │
│ (Port 27017)│
└──────────────┘
Backend (Task A)
- NestJS monorepo with
apps/gatewayandapps/authentication - TCP microservice communication via
@nestjs/microservices - MVC pattern with Controller → Service → Repository layers
- JWT authentication with Passport.js
- MongoDB with Typegoose (decorator-based schemas with full TypeScript type inference)
- Environment validation with Zod (TypeScript-first schema validation)
- Swagger API documentation
- Rate limiting, health checks, centralized logging
- Input validation with class-validator and DTOs/RTOs
- Unit and E2E tests with Jest
- Docker multi-stage builds
Frontend (Task B)
- Next.js 16 with App Router (server and client components)
- 8 reusable UI components: Button, InputField, Modal, Card, Tabs, Toast, Badge, Spinner
- Full accessibility (WCAG 2.1 Level AA) with ARIA attributes and keyboard navigation
- Dark mode with system preference detection and persistence
- JWT auth flow with protected routes
- Responsive design (mobile-first)
- Vitest + React Testing Library (unit/component tests)
- Playwright (E2E browser tests — registration, login, dark mode, responsive, accessibility)
- ESLint + Prettier configured
- TailwindCSS styling
# Clone the repository
git clone <repository-url>
cd ricmancio-fullstack-microservices
# Start all services docker engine v29.2.0
docker compose up --build
# Services:
# Frontend: http://localhost:8080
# Gateway API: http://localhost:3000
# Swagger Docs: http://localhost:3000/api/docs
# MongoDB: localhost:27017Prerequisites: Node.js 20+, pnpm 8+, MongoDB 8+
# 1. Start MongoDB locally (or via Docker)
docker run -d -p 27017:27017 --name mongodb mongo:8
# 2. Backend setup
cd backend
cp .env.example .env
pnpm install
pnpm start:dev
# 3. Frontend setup (in a new terminal)
cd frontend
cp .env.local.example .env.local
pnpm install
pnpm devOpen http://localhost:3000 for the frontend and http://localhost:3000/api/docs for Swagger.
Note: When running locally, both the frontend dev server and gateway default to port 3000. Either change the frontend to a different port in
package.json("dev": "next dev -p 8080") or use Docker Compose which handles this automatically.
| Method | Endpoint | Auth Required | Description |
|---|---|---|---|
| POST | /auth/register |
No | Register a new user |
| POST | /auth/login |
No | Login, returns JWT |
| GET | /auth/users |
Bearer Token | Get all users |
| GET | /auth/profile |
Bearer Token | Get current user |
| GET | /health |
No | Health check |
curl -X POST http://localhost:3000/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "john@example.com",
"password": "SecurePass123!",
"firstName": "John",
"lastName": "Doe"
}'curl -X POST http://localhost:3000/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "john@example.com",
"password": "SecurePass123!"
}'curl http://localhost:3000/auth/users \
-H "Authorization: Bearer <your-jwt-token>"ricmancio-fullstack-microservices/
├── backend/
│ ├── apps/
│ │ ├── gateway/ # HTTP API Gateway
│ │ └── authentication/ # Authentication Microservice
│ ├── common/ # Shared DTOs, filters, decorators
│ ├── core/ # Base abstractions, logger
│ ├── config/ # Environment configuration
│ ├── docker/ # Dockerfiles
│ ├── test/ # E2E tests
│ └── docker-compose.yml
│
├── frontend/
│ ├── src/
│ │ ├── app/ # Pages (Home, Register, Login, Users)
│ │ ├── components/
│ │ │ ├── ui/ # Reusable component library
│ │ │ ├── features/ # Feature components
│ │ │ └── layout/ # Header, Footer, Navigation
│ │ ├── hooks/ # Custom React hooks
│ │ ├── lib/ # API client, utilities
│ │ ├── providers/ # Auth, Theme, Toast providers
│ │ └── types/ # TypeScript definitions
│ └── Dockerfile
│
├── docker-compose.yml # Full-stack orchestration
└── README.md
# Backend unit tests
cd backend && pnpm test
# Backend E2E tests
cd backend && pnpm test:e2e
# Frontend component tests
cd frontend && pnpm test
# Frontend coverage report
cd frontend && pnpm test:coverage
# Frontend E2E tests (Playwright)
cd frontend && pnpm test:e2e
# Frontend E2E with visible browser
cd frontend && pnpm test:e2e:headed| Layer | Technology |
|---|---|
| Frontend | Next.js 16, React 19, TypeScript, TailwindCSS |
| Backend | NestJS, TypeScript, Typegoose, Zod |
| Database | MongoDB 8 |
| Auth | JWT, Passport.js, bcrypt |
| Communication | TCP Microservices (@nestjs/microservices) |
| Testing | Jest, Vitest, React Testing Library, Playwright |
| DevOps | Docker, Docker Compose, multi-stage builds |
| Package Mgr | pnpm |
| Docs | Swagger/OpenAPI |
Why Microservices with TCP? TCP provides low-latency, synchronous request/response communication between services. It's built into NestJS and ideal for co-located services that need reliable, fast communication.
Why Repository Pattern? Abstracts database operations behind a clean interface, making the code testable and the database layer swappable without changing business logic.
Why DTOs and RTOs? DTOs validate incoming data. RTOs (Response Transfer Objects) shape outgoing data, ensuring sensitive fields like passwords are never exposed.
Why Typegoose over Mongoose? Typegoose uses TypeScript decorators to define schemas — the same pattern NestJS uses for everything else. It provides automatic type inference, eliminating the need to maintain separate TypeScript interfaces alongside Mongoose schemas. One class definition gives you both the schema and the type.
Why Zod over Joi?
Zod is TypeScript-first with native type inference (z.infer<typeof schema>). Joi requires separate type definitions. Zod also produces smaller bundles and has become the standard for modern TypeScript projects.
Why pnpm? pnpm is faster than npm, uses hard links to save disk space, and enforces a strict dependency tree that prevents phantom dependencies. It's the modern standard for Node.js monorepos.
Why Playwright for E2E? Playwright provides cross-browser testing with a modern async API, auto-waiting, and built-in mobile emulation. Tests run against a real browser, catching issues that unit tests miss — like navigation flows, form validation UX, and responsive layout.
Why App Router? Next.js 16 App Router enables server components for better performance and SEO, while client components handle interactivity where needed.
I document every experiment, feature, and lesson learned building SnippetForm in my weekly newsletter.
MIT
Riccardo Mancinelli — ricmancio@gmail.com