IU — Video Game Character Management

---

1. Project Overview

IU is a full-stack web application for managing video game characters and their associated game metadata. It ships a role-based access control system where Admins can create, update, and delete records while regular Users have read-only access.

Service	URL
Frontend (Angular)	http://localhost:4200
Backend API (.NET)	http://localhost:5293
API Docs (Scalar)	http://localhost:5293/scalar/v1
pgAdmin 4	http://localhost:5050
PostgreSQL	localhost:5432

---

2. Tech Stack

📖 Detailed documentation for each sub-project:

• Frontend: client/README.md
• Backend: server/README.md

Layer	Technology
Frontend	Angular 19, PrimeNG 19, Tailwind CSS, RxJS
Backend	.NET 10, ASP.NET Core Web API, Entity Framework Core
Database	PostgreSQL 16
Auth	JWT Bearer Tokens
Infrastructure	Docker, Docker Compose
Dev Tools	Scalar UI, pgAdmin 4, Makefile

---

3. System Architecture

┌─────────────────────────────────────────────────────────┐
│                      Browser                            │
│              Angular 19 SPA (:4200)                     │
│   PrimeNG · Tailwind · Signals · Lazy-loaded routes     │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTP / JSON (JWT)
┌──────────────────────▼──────────────────────────────────┐
│              .NET 10 Web API (:5293)                    │
│   Controllers → Services → EF Core → PostgreSQL         │
│   JWT Auth · CORS · Scalar Docs                         │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│          PostgreSQL 16 (Docker :5432)                   │
│          pgAdmin 4 (Docker :5050)                       │
└─────────────────────────────────────────────────────────┘

Monorepo structure:

project-root/
├── client/              # Angular 19 SPA
├── server/              # .NET 10 Web API
│   └── VideoGameCharacterApi/
├── db/                  # SQL seed scripts
│   ├── seed_data.sql    # First-run init (Docker entrypoint)
│   └── seed_only.sql    # Idempotent re-seed (ON CONFLICT DO NOTHING)
├── docker-compose.yml
├── Makefile
└── .env.example

---

4. Features

Feature	Admin	User
View characters & games	✅	✅
Create / Edit / Delete characters	✅	❌
Create / Edit / Delete games	✅	❌
Assign characters to games	✅	❌
View users	✅	✅
Manage users (create, edit, delete, change password)	✅	❌
Manage roles	✅	❌
Register & Login	✅	✅

Pre-seeded accounts:

Role	Username	Password
Admin	admin	Test@123456
User	alice	Test@123456
User	bob / charlie / diana	User@12345

---

5. Environment Variables

Copy the example and fill in your values:

cp .env.example .env.local

Variable	Description
ConnectionStrings__DefaultConnection	PostgreSQL connection string for .NET
Jwt__Key	Secret key for JWT signing (min 32 chars)
POSTGRES_DB	Database name (must match connection string)
POSTGRES_USER	Database username
POSTGRES_PASSWORD	Database password
PGADMIN_DEFAULT_EMAIL	pgAdmin login email
PGADMIN_DEFAULT_PASSWORD	pgAdmin login password

---

6. Makefile Commands

Run make help to see all available targets.

Command	Description
make setup	Copy .env.example → .env.local
make install	Install client npm deps + restore server nuget packages
make build	Build Angular client + publish .NET server
make lint	Format client code with Prettier
make test	Run backend unit tests
Docker
make up	Start PostgreSQL + pgAdmin containers
make down	Stop containers
make logs	Tail container logs
make status	Show container status
make clean	Stop containers, remove volumes & build artifacts
Database
make seed-db	Re-seed the running database (idempotent)
Development
make dev	make up + start client & server concurrently
make dotnet-dev	Run backend only (Development env)
make dotnet-prod	Run backend only (Production env)
Utilities
make docker-engine-start	Open Docker Desktop (macOS)
make docker-engine-status	Show Docker Engine info

---

7. Quick Start

Prerequisites

• .NET 10 SDK
• Node.js v20+
• Docker & Docker Compose

Setup

git clone <repo-url> && cd IU

make setup    # Copy .env.example → .env.local (fill in your values before next step)
make install  # Install client npm deps + restore server NuGet packages

make up       # Start Docker services (PostgreSQL + pgAdmin)
make seed-db  # Load mock data

make dev      # Start backend + frontend

Tip: Run make help to see all available targets.

---

8. API Docs

The API is fully documented with Scalar UI (OpenAPI):

• Interactive UI: http://localhost:5293/scalar/v1
• OpenAPI JSON: http://localhost:5293/openapi/v1.json

Group	Endpoints
Auth	POST /api/auth/login, POST /api/auth/register, GET /api/auth/me
Characters	GET/POST /api/videogamecharacters, GET/PUT/DELETE /api/videogamecharacters/{id}
Games	GET/POST /api/games, GET/PUT/DELETE /api/games/{id}, POST/DELETE /api/games/{gameId}/characters/{characterId}
Users	GET/POST /api/users, GET/PUT/DELETE /api/users/{id}, PUT /api/users/{id}/password
Roles	GET/POST /api/roles, GET/PUT/DELETE /api/roles/{id}

All endpoints (except login and register) require a Bearer JWT token in the Authorization header.

---

9. Development Workflow

# Run tests
make test                          # backend unit tests
cd client && npm test              # frontend unit tests (Karma + Jasmine)

# Lint & format
cd client && npm run format        # Prettier

# Re-seed the database (without restarting Docker)
make seed-db

# Full clean rebuild
make clean && make install && make dev

---

10. Contributors

Name	Role
Nguyen Minh Phuc	Full-stack Developer