AckLab

AckLab is a production-oriented Next.js MVP for interactive networking fundamentals. It includes subnet visualization, binary conversion, TCP handshake animation, OSI exploration, DNS flow simulation, and graph-based routing.

The current product is intentionally local-mock only. It does not implement a backend, database, authentication, payments, subscriptions, or external APIs.

Tech Stack

• Next.js App Router with standalone production output
• TypeScript strict mode
• TailwindCSS v4
• shadcn-compatible UI primitives
• Framer Motion
• Lucide React
• React Hook Form and Zod
• Zustand
• pnpm
• ESLint, Prettier, Husky, lint-staged
• Docker multi-stage production build
• GitHub Actions CI

Architecture

app/                  App Router pages and global layout
src/components/ui/    shadcn-compatible primitives
src/components/layout/ shell, nav, command menu, theme provider
src/components/shared/ reusable product UI
src/components/visualizations/
src/features/         domain-owned interactive tools and visualizers
src/data/             local mock data
src/types/            shared TypeScript contracts
src/config/           app and environment configuration
src/constants/        navigation and constants
docs/                 architecture and deployment documentation

Local Setup

Use pnpm through Corepack:

corepack enable
corepack prepare pnpm@11.0.9 --activate
pnpm install
cp .env.example .env.local
pnpm dev

Open http://localhost:3000.

Scripts

pnpm dev              # start local Next.js dev server
pnpm build            # create production build
pnpm start            # run production server after build
pnpm lint             # run ESLint
pnpm typecheck        # run TypeScript checks
pnpm test             # run Vitest unit tests
pnpm format           # write Prettier formatting
pnpm format:check     # verify Prettier formatting
pnpm docker:build     # build local production Docker image
pnpm docker:run       # run local production Docker image
pnpm docker:compose   # run Compose-based local container test
pnpm clean            # remove generated build artifacts

Next version floor

Stay on Next >= 16.3.0. On 16.2.6 the Turbopack dev server spawned an unbounded number of .next/dev/build/postcss.js child processes when compiling a page (500+ within 20 seconds), saturating every core and hard-freezing the machine. experimental.turbopackPluginRuntimeStrategy: "workerThreads" was not a workaround — it throws ERR_SOCKET_BAD_PORT in createIpc and hangs the compile. 16.3.0 fixes both that and the workspace-root inference; if you ever need to downgrade, run next dev --webpack instead.

Environment Variables

Environment validation lives in src/config/env.ts.

Copy .env.example to .env.local for local development:

cp .env.example .env.local

Public variables:

• NEXT_PUBLIC_APP_URL: browser-visible app URL.

Do not expose secrets through NEXT_PUBLIC_. Any value with that prefix can be bundled into client-side JavaScript.

Docker

Build and run the production image:

pnpm docker:build
pnpm docker:run

Or use Compose for local container testing:

pnpm docker:compose

The Dockerfile uses:

• pnpm with frozen lockfile
• multi-stage builds
• Next.js output: "standalone"
• non-root runtime user
• port 3000

No PostgreSQL, Redis, Nginx, Kubernetes, Terraform, or cloud-specific infrastructure is included.

CI/CD

GitHub Actions workflow: .github/workflows/ci.yml

CI runs on push and pull_request:

• checkout
• setup pnpm
• setup Node.js
• install with frozen lockfile
• lint
• typecheck
• test
• build

Deployment

Vercel

1. Import the repository into Vercel.
2. Use pnpm as the package manager.
3. Build command: pnpm build.
4. Add NEXT_PUBLIC_APP_URL for each environment.
5. Keep future secrets server-only and never prefix private values with NEXT_PUBLIC_.

Docker

Use the included Dockerfile for production-style container builds:

docker build -t acklab:local .
docker run --rm -p 3000:3000 acklab:local

Security Defaults

• Security headers are configured in next.config.ts.
• An enforced Content Security Policy is configured in next.config.ts. script-src still allows 'unsafe-inline' and 'unsafe-eval' because Next's bootstrap requires them; tightening that needs per-request nonces.
• upgrade-insecure-requests is sent in production builds only. The dev server is HTTP, so the directive rewrites every subresource to https and the app renders with no CSS or JS at all. Safari upgrades even on localhost; Chrome exempts localhost but not a bare LAN IP, so it breaks on the Network: URL that next dev prints. Chrome on localhost is the one combination that hides this — check Safari before assuming a CSP change is dev-safe.
• No secrets are required for the MVP.
• .env.local and other local environment files are ignored by Git.
• Runtime Docker container runs as a non-root user.

Dependency audit:

pnpm audit

Contribution Workflow

1. Create a branch.
2. Run pnpm install.
3. Make scoped changes.
4. Run pnpm lint, pnpm typecheck, and pnpm build.
5. Commit with the Husky pre-commit hook enabled.
6. Open a pull request and wait for CI.

Roadmap

• Course paths and guided lessons
• Quiz engine with review mode
• User progress persistence
• Packet analyzer and HTTP inspector
• Port reference and latency visualizer
• Secure auth, RBAC, subscriptions, and billing
• Rate limiting, analytics, secure sessions, and audit logs
• Admin dashboard

See docs/architecture.md and docs/deployment.md for more detail.