Employee & Project Allocation, Tracking & Management Platform - Angular, TypeScript, MongoDB, Prisma, Serverless API, AI Drafting, Contentful, Resend Full-Stack Project (including Real-time Dashboard, Calendar, Timeline, Gantt Chart, Business Insights)

EmpowerHub is a comprehensive, full-stack Employee & Project Management learning project built with Angular 20, a Vercel serverless API, Prisma + MongoDB, optional AI overview drafting, Contentful briefs, and email notifications (Resend / SMTP). It demonstrates real-world CRUD, session auth, dashboards, calendar / Gantt / timeline views, business insights, and API docs & monitoring.

Live demo: https://employee-project-management.vercel.app/
Security: Private reports → SECURITY.md · contact@arnobmahmud.com
Author: Arnob Mahmud | LinkedIn: https://www.linkedin.com/in/arnob-mahmud-05839655/ | GitHub: https://github.com/arnobt78

Overview
Who This Project Is For
Features
Technology Stack
Architecture Walkthrough
Project Structure
Getting Started
Environment Variables
Demo Login
Routes & Navigation
API Endpoints
Backend & Data Layer
Frontend Components & Reuse
Key Libraries Explained
Code Snippets for Learners
Scripts Reference
Deployment (Vercel)
Observability (Sentry)
Further Docs in This Repo
Keywords
Conclusion
License
Happy Coding

Overview

EmpowerHub helps learners explore how a modern SPA talks to a serverless backend and a document database:

Layer	What it does
Angular SPA	Pages for login, dashboard, employees, projects, assignments, insights, calendar/timeline, API docs/status
API	Node handlers under `api/employee-management/` on Vercel (locally via `tools/dev-api-server.mjs`)
Database	MongoDB via Prisma (`prisma/schema.prisma`) with a native Mongo fallback path where needed
Auth	HttpOnly session cookie (`eh_session`), bcrypt-hashed demo user, route guards
Extras	AI overview draft (multi-provider fallback), Contentful brief fetch, email notifications, Sentry tunnel

You can run the UI against the live demo immediately, or clone and run locally with MongoDB. Most optional services (AI, CMS, email, Sentry) can stay empty—the core CRUD and UI still work when DATABASE_URL and a seeded auth user are available.

Who This Project Is For

Beginners learning Angular standalone components, signals, and RxJS Observables
Developers exploring serverless APIs on Vercel without a long-running Node server in production
Anyone wanting a portfolio CRUD app with dashboards, charts-like schedule views, and API status pages
Learners studying session cookies, route guards, and API auth middleware

Features

Core product features

Authentication — Demo admin login with bcrypt + HttpOnly cookie; authGuard / guestGuard
Employees — Full CRUD with department hierarchy (parent / child)
Projects — Create/update/delete, approval workflow, reviewer comments, rich project form
Project assignments — Link employees to projects with roles and allocation fields
Dashboard — Aggregated KPIs with loading skeletons (avoids empty-state flash)
Business insights — Analytics over projects and assignments
Calendar, timeline & Gantt — Schedule visualization components
API documentation & status — In-app docs plus live request monitoring metrics
Notifications — Optional Resend and/or SMTP emails on key CRUD / approval events
AI overview drafting — Optional Gemini → Groq → OpenRouter :free → Hugging Face fallback
Contentful briefs — Optional CMS fetch into project overview
Error tracking — Optional Sentry with same-origin tunnel /api/monitoring (ad-blocker friendly)

Learning-oriented features

Single API client: MasterService (prefer extending this over adding new HTTP clients)
Feature flags via public env (NG_APP_FEATURE_*)
.env.example documents every variable and where to obtain keys
Lint (npm run lint), unit tests (npm test), production build (npm run build)

Technology Stack

Area	Choice	Why it matters (beginner note)
UI	Angular 20 (standalone)	Components without NgModules; modern default
Language	TypeScript ~5.8	Types catch mistakes before runtime
Styling	Tailwind CSS 3.4 + shadcn-style UI	Utility classes + reusable button/cva patterns
Icons	Lucide Angular	Icon sets for nav and actions
State / HTTP	RxJS + `HttpClient`	Streams for async API calls
API	Vercel Serverless Functions	Pay-per-request backend, no always-on server
ORM / DB	Prisma 6 + MongoDB	Schema in code; Mongo for flexible documents
Auth	bcryptjs + HttpOnly cookies	Password hashing; cookie not readable by JS
Email	Resend API and/or Nodemailer SMTP	Transactional mail
AI	Gemini / Groq / OpenRouter / HF	Free-tier fallback chain
CMS	Contentful Delivery API	Headless content for project briefs
Errors	Sentry (`@sentry/angular` + tunnel)	Production error visibility
Hosting	Vercel	Static Angular `dist/` + `/api/*` functions

Architecture Walkthrough

Browser (Angular SPA)
    │  HTTPS / proxy in dev
    ▼
MasterService  ──►  /api/employee-management/<Action>
    │
    ▼
[...segments].js  →  handler.mjs  →  repository.mjs / auth.mjs / notifications.mjs / ai-providers.mjs
    │
    ▼
Prisma / MongoDB

Local development: ng serve proxies /api/employee-management and /api/monitoring to http://localhost:4310 (proxy.conf.json + tools/dev-api-server.mjs).

Production: Vercel serves Angular dist/ (framework preset) and runs api/employee-management/[...segments].js plus api/monitoring.js (Sentry tunnel).

Project Structure

employee-management/
├── src/
│   ├── index.html                 # SEO metadata, canonical URL, JSON-LD
│   ├── environments/              # Public client config (no secrets)
│   └── app/
│       ├── app.routes.ts          # Routes + guards
│       ├── pages/                 # Feature pages (login, dashboard, CRUD, …)
│       ├── components/            # Calendar, Gantt, timeline, UI primitives
│       ├── service/               # MasterService, AuthService
│       ├── guards/                # authGuard, guestGuard
│       ├── interceptors/          # credentials + 401 handling
│       ├── lib/sentry/            # Client Sentry init + noise filters
│       └── model/                 # Interfaces + Employee class
├── api/
│   ├── monitoring.js              # Sentry same-origin tunnel
│   ├── _lib/                      # prisma-client, sentry helpers
│   └── employee-management/
│       ├── [...segments].js       # Vercel entry
│       ├── handler.mjs            # Routing + auth + notifications triggers
│       ├── repository.mjs         # Data access + AI/CMS helpers
│       ├── auth.mjs               # Login / session / logout
│       ├── notifications.mjs      # Resend / SMTP
│       ├── ai-providers.mjs       # LLM fallback chain
│       └── monitoring.mjs         # In-memory API request metrics (not Sentry)
├── prisma/                        # schema.prisma + seed
├── tools/                         # dev-api-server, seed-demo-user, env/sentry scripts
├── public/                        # favicon, robots.txt, sitemap.xml
├── docs/                          # Playbooks, LLM selection, Sentry guide
├── .env.example                   # Template (copy to .env)
├── SECURITY.md                    # Private vulnerability reporting
├── vercel.json                    # Output dir, headers, function limits
└── package.json

Getting Started

Prerequisites

Node.js 24.x (see engines in package.json; .nvmrc if present)
npm
MongoDB reachable via a connection string (local or Atlas / VPS)

1. Clone and install

git clone https://github.com/arnobt78/Employee-Management--Angular-FullStack-Fundamental-Project-1.git
cd Employee-Management--Angular-FullStack-Fundamental-Project-1
npm install

postinstall generates src/environments/environment.prod.ts (gitignored).

2. Environment file (optional but recommended)

cp .env.example .env

Minimum for a useful local demo:

Set DATABASE_URL to your MongoDB URI
Seed domain data from dataset/: npm run db:seed
Seed the demo auth user: npm run db:seed:auth

To wipe and reseed a local Mongo only: ALLOW_DB_WIPE=1 npm run db:reseed:local (refuses non-localhost unless EH_ALLOW_REMOTE_WIPE=1 / EH_ALLOW_ATLAS_WIPE=1).

You do not need AI, CMS, email, or Sentry keys to explore CRUD UI. Leave those blank; features that need them simply stay disabled or no-op.

3. Run frontend + API together

npm start

This runs:

API on http://localhost:4310 (npm run api:dev)
Angular on http://localhost:4200 with proxy (npm run start:frontend)

Open http://localhost:4200 → sign in with the demo account.

4. Validate

npm run lint
npm test -- --watch=false --browsers=ChromeHeadless
npm run build

Environment Variables

Copy .env.example → .env. Never commit .env.

Do we need a `.env`?

Goal	Need `.env`?
Browse the live Vercel demo	No
Run UI + API locally with real data	Yes — at least `DATABASE_URL` (+ seed auth)
AI overview draft	Optional — `GOOGLE_GEMINI_API_KEY` and/or Groq / OpenRouter / HF
Contentful briefs	Optional — `CMS_*`
Email notifications	Optional — `RESEND_TOKEN` and/or `SMTP_*`
Sentry	Optional — empty DSN disables Sentry

Critical rule: do not put secrets under `NG_APP_*`

This Angular build does not inject Vercel NG_APP_* secrets into a secure server-only store for the API. AI / CMS / email / DB / SENTRY_AUTH_TOKEN must stay unprefixed server env vars. NG_APP_* is only for public client-safe values (API base path, feature flags). DSN for Sentry is public by design and is baked at build from SENTRY_DSN.

Variable catalog

Always useful (local / production)

Variable	Purpose	Where to get it
`DATABASE_URL`	MongoDB connection for Prisma	MongoDB Atlas or your host
`APP_BASE_URL`	Links in emails; OpenRouter referer	Local: `http://localhost:4200` · Prod: your Vercel URL
`NG_APP_API_BASE_URL`	Client API prefix	Usually `/api/employee-management/`
`API_PORT`	Local API port	Default `4310`
`SESSION_TTL_HOURS`	Session cookie lifetime	Default `24`

Feature flags (public / client-safe)

NG_APP_FEATURE_READINESS_V2=true
NG_APP_FEATURE_AI_SUMMARY=false
NG_APP_FEATURE_WORKFLOW_TIMELINE=false

AI (server-only, optional)

GOOGLE_GEMINI_API_KEY=     # https://aistudio.google.com/apikey
GROQ_LLAMA_API_KEY=        # https://console.groq.com/keys
OPENROUTER_API_KEY=        # https://openrouter.ai/keys  (use :free models)
HUGGINGFACE_API_KEY=       # https://huggingface.co/settings/tokens

Fallback order: Gemini → Groq → OpenRouter :free → Hugging Face. See docs/LLM_MODEL_SELECTION.md.

Contentful (server-only, optional)

CMS_SPACE_ID=
CMS_ENVIRONMENT=master
CMS_DELIVERY_TOKEN=
CMS_PREVIEW_TOKEN=

From Contentful → Settings → API keys.

Email (server-only, optional)

RESEND_TOKEN=              # https://resend.com/api-keys
SMTP_HOST=
SMTP_PORT=587
SMTP_USER=
SMTP_PASS=
EMAIL_FROM="EmpowerHub <no-reply@example.com>"
EMAIL_DRY_RUN=false        # true = log only, do not send
NOTIFY_APPROVAL_TO=        # optional always-notify list (comma-separated)

Sentry (optional)

SENTRY_DSN=                # Project → Client Keys (DSN)
SENTRY_ORG=
SENTRY_PROJECT=employee-management
SENTRY_AUTH_TOKEN=         # CI source maps only — never in the browser bundle

Same-origin tunnel: POST /api/monitoring. Details: .env.example and docs/Redis_Sentry_PostHog_INTEGRATION_GUIDE.md.

Vercel checklist

Set production/preview env for at least: DATABASE_URL, APP_BASE_URL (live URL), then redeploy. Add optional AI/CMS/email/Sentry as needed. After changing env, redeploy so build-time DSN bake and serverless functions pick up values.

Demo Login

Field	Value
Username	`admin`
Password	`112233`

Seed / refresh the hashed user:

npm run db:seed:auth

Do not put demo passwords in Vercel as NG_APP_DEMO_PASSWORD. The login form autofill uses public demo constants for learning; production apps should replace this with real identity providers.

Routes & Navigation

Defined in src/app/app.routes.ts:

Path	Page	Guard
`/`	Redirect → `/login`	—
`/login`	Sign in	`guestGuard`
`/dashboard`	KPIs	`authGuard`
`/employee`	Employee CRUD	`authGuard`
`/projects`	Project list	`authGuard`
`/new-project`	Create project	`authGuard`
`/update-project/:id`	Edit project	`authGuard`
`/project-employee`	Assignments	`authGuard`
`/business-insights`	Analytics	`authGuard`
`/calendar-timeline`	Calendar / timeline / Gantt	`authGuard`
`/api-doc`	API documentation UI	`authGuard`
`/api-status`	Live API health UI	`authGuard`

Private pages nest under LayoutComponent (shell nav + outlet).

API Endpoints

Base path: /api/employee-management/<Action>

Most actions require an authenticated session cookie. Public-ish actions include login/demo listing (see isPublicAction in auth.mjs / handler).

Auth

Method	Action	Description
POST	`Login`	Authenticate; sets `eh_session`
POST	`Logout`	Clears session
GET	`Session`	Current session
GET	`GetDemoAccounts`	Demo account hints

Departments

Method	Action	Description
GET	`GetParentDepartment`	Parent departments
GET	`GetChildDepartmentByParentId`	Children by parent id

Employees

Method	Action	Description
GET	`GetAllEmployees`	List
POST	`CreateEmployee`	Create
PUT	`UpdateEmployee`	Update
DELETE	`DeleteEmployee`	Delete

Projects

Method	Action	Description
GET	`GetAllProjects` / `GetProject`	List / one
POST	`CreateProject`	Create
PUT	`UpdateProject`	Update
DELETE	`DeleteProject`	Delete
POST	`RequestApproval` / `ApproveProject` / `RejectProject` / `ResetProjectApproval`	Approval flow
POST	`AddReviewerComment` / `ResolveReviewerComment`	Reviewer comments
GET	`GetProjectResources`	Resource insights
GET	`GetContentfulBrief`	Optional CMS brief
POST	`GenerateOverviewDraft`	Optional AI draft

Assignments

Method	Action	Description
GET	`GetAllProjectEmployees`	List
POST	`CreateProjectEmployee`	Create
PUT	`UpdateProjectEmployee`	Update
DELETE	`DeleteProjectEmployee`	Delete

Dashboard / schedule / meta

Method	Action	Description
GET	`GetDashboard`	Aggregates
GET	`GetSchedule`	Calendar/Gantt data
GET	`GetApiStatus`	Monitoring snapshot
GET	`GetApiDocumentation`	OpenAPI-like doc payload

Sentry tunnel (separate route)

Method	Path	Description
POST	`/api/monitoring`	Forwards Sentry envelopes (DSN allowlisted)

Example client call pattern (MasterService):

this.http.get(`${environment.api.baseUrl}GetAllEmployees`, {
  withCredentials: true,
});

Backend & Data Layer

Request flow

Vercel (or local HTTP server) receives /api/employee-management/...
handler.mjs parses action + method, checks session unless public
Calls repository.mjs (Prisma) for persistence
May trigger notifications.mjs or ai-providers.mjs
Logs metrics via monitoring.mjs (in-memory; resets on cold start)

Prisma models (high level)

DepartmentParent / DepartmentChild
Employee
Project
ProjectEmployee (assignments)
AppUser / Session (auth)
Counter (id helpers where used)

Schema: prisma/schema.prisma.

Notifications

Emails fire on many create/update/delete/approval paths. Recipients come from project stakeholders plus optional NOTIFY_APPROVAL_TO. With EMAIL_DRY_RUN=true, the app logs instead of sending.

Frontend Components & Reuse

Pages (`src/app/pages/`)

Each page is a standalone component (.ts + .html + .css). To reuse a page pattern in another Angular app:

Copy the page folder
Register a route
Inject MasterService / AuthService (or replace with your API)
Keep loading flags + skeletons so lists do not flash empty values

Shared UI & views (`src/app/components/`)

Piece	Role	Reuse tip
`calendar-view`	Month grid + events	Pass `events[]` with `title`, dates, `description`
`timeline-view`	Horizontal timeline	Feed schedule items from `GetSchedule`
`gantt-view`	Bar chart by project dates	Map projects → start/end
`ui/button`	CVA-based button variants	Import and use `btnVariants` / component
`ui/toast` + `ToastService`	Non-blocking feedback	`toast.show({ title, description })`
`ui/select-menu`	Accessible dropdown (CDK overlay)	Prefer over native `<select>` for styled menus
`ui/list-skeleton`	Loading placeholders	Bind while `isLoading`
`ui/floating-background`	Decorative bg	Drop into auth/marketing shells
`ui/optimized-image`	Image helper	Swap `src` / alt

Services

MasterService — Central HTTP API + short in-memory cache with invalidation after mutations. Prefer extending this for new endpoints.
AuthService — Login/logout/session; used by guards and interceptor.

Guards & interceptor

authGuard — Redirect unauthenticated users to /login
guestGuard — Keep logged-in users off /login
authInterceptor — withCredentials: true; handle 401

Key Libraries Explained

Library	What it is	How we use it
Angular	SPA framework	Routing, forms, DI, standalone components
RxJS	Reactive streams	`Observable` HTTP results, `shareReplay` cache
Prisma	ORM	Type-safe Mongo access from serverless Node
bcryptjs	Password hashing	Demo `AppUser` password storage
Tailwind	Utility CSS	Layout, dark glass UI, responsive spacing
class-variance-authority (cva)	Variant API	Button size/intent classes
Lucide	Icons	Consistent iconography
Nodemailer / Resend	Email	Transactional notifications
Sentry	Errors	Client + server + quiet source maps
dotenv	Env loader	Local API + tooling

Code Snippets for Learners

Feature flag check

import { environment } from "../environments/environment";

if (environment.featureToggles.aiSummaryGenerator) {
  // show AI draft button
}

Toast after save

this.toast.show({
  title: "Project created",
  description: "A new project is now tracked in the system.",
});

Auth guard idea (simplified)

export const authGuard: CanActivateFn = () => {
  const auth = inject(AuthService);
  const router = inject(Router);
  return auth.ensureSession().pipe(map((ok) => (ok ? true : router.createUrlTree(["/login"]))));
};

Server AI fallback (concept)

// api/employee-management/ai-providers.mjs
// Tries Gemini → Groq → OpenRouter (:free) → Hugging Face
const completion = await completeChatWithFallback(prompt);

Scripts Reference

Script	Purpose
`npm start`	API + Angular concurrently
`npm run start:frontend`	`ng serve` + proxy
`npm run api:dev`	Local API on `API_PORT`
`npm run build`	Generate prod env → `ng build` → quiet Sentry map upload
`npm run lint` / `lint:fix`	ESLint via Angular
`npm test`	Karma / Jasmine
`npm run db:seed`	Domain seed from repo `dataset/`
`npm run db:seed:auth`	Demo `admin` user
`npm run db:wipe:local`	Clear domain collections (requires `ALLOW_DB_WIPE=1`; localhost only unless override)
`npm run db:reseed:local`	Wipe → `db:seed` → `db:seed:auth` (local gate as above)

Deployment (Vercel)

Import the GitHub repo into Vercel
Set env vars (see above); APP_BASE_URL = production URL
Build command uses npm run build (Angular output: dist/, detected by Vercel’s Angular preset)
Redeploy after any env change

Headers in vercel.json discourage caching of API responses and set basic security headers.

Observability (Sentry)

Client SDK posts to /api/monitoring (not directly to ingest.sentry.io) so ad blockers are less likely to drop events
Noise filters drop extension / benign browser noise
Source maps upload only when SENTRY_ORG + SENTRY_PROJECT + SENTRY_AUTH_TOKEN are set; maps are deleted from dist/ afterward

Further Docs in This Repo

Doc	Topic
`.env.example`	Full env template
`SECURITY.md`	Private vulnerability reporting
`docs/LLM_MODEL_SELECTION.md`	Free-tier model choices
`docs/Redis_Sentry_PostHog_INTEGRATION_GUIDE.md`	Sentry tunnel / quiet CI patterns
`docs/UI_STYLING_GUIDE.md`	UI conventions
`docs/VERCEL_PRODUCTION_GUARDRAILS.md`	Production tips
`docs/PROJECT_ENGINEERING_PLAYBOOK.md`	Engineering playbook
`docs/AGILE_V_PROTOCOL.md`	Agile V agent workflow

Keywords

Technologies: Angular 20, TypeScript, RxJS, Tailwind CSS, Shadcn-style UI, Prisma, MongoDB, Vercel Serverless, Node.js, bcrypt, Sentry, Resend, Nodemailer, Contentful, Gemini, Groq, OpenRouter, Hugging Face

Concepts: CRUD, REST-style action routes, HttpOnly sessions, route guards, HTTP interceptors, serverless cold starts, SPA SEO (index.html meta + sitemap), feature flags, multi-provider AI fallback, approval workflows

Features: Dashboard KPIs, employee/project CRUD, assignments, calendar, timeline, Gantt, business insights, API docs, API status monitoring, email notifications, AI overview drafting

Learning: Standalone components, signals, Observables, reusable UI primitives, repository pattern in serverless handlers, environment hygiene (server vs NG_APP_*)

Conclusion

EmpowerHub is a portfolio-ready, educational full-stack application that connects an Angular SPA to a serverless MongoDB-backed API. Use it to study:

Modern Angular 20 patterns (standalone, guards, interceptors, signals)
Serverless request handling and Prisma data access
Practical auth, CRUD, dashboards, and optional AI / CMS / email / Sentry integrations

Clone it, seed the demo user, explore the live demo, then extend MasterService and repository.mjs for your own domain.

License

This project is licensed under the MIT License. Feel free to use, modify, and distribute the code as per the terms of the license.

Happy Coding! 🎉

This is an open-source project — feel free to use, enhance, and extend this project further!

If you have any questions or want to share your work, reach out via GitHub or my portfolio at https://www.arnobmahmud.com.

Private security reports: SECURITY.md · contact@arnobmahmud.com

Name		Name	Last commit message	Last commit date
.agile-v		.agile-v
api		api
dataset		dataset
docs		docs
prisma		prisma
public		public
src		src
tools		tools
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
angular.json		angular.json
components.json		components.json
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
prisma.config.ts		prisma.config.ts
proxy.conf.json		proxy.conf.json
tailwind.config.js		tailwind.config.js
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.spec.json		tsconfig.spec.json
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation