Documentation

Home

K12 Backend Core (Microservices)

This project is part of the K12 Backend Ecosystem, built with TypeScript, Express.js, and Node.js 22.
It follows a microservices architecture, where each domain is isolated into an independent service.

Currently, the system includes:

  • Core Service – user management, reports, investigations
  • Auth Service – standalone authentication & authorization microservice (JWT, refresh tokens, sessions)
  • Investigations Infrastructure – investigation workflows

Each service communicates via gRPC (synchronous) and Redis Pub/Sub (asynchronous).
Shared contracts (.proto files, DTOs, enums, interfaces) are maintained in a common package.

Requirements

  • Node.js v22 or higher
  • pnpm for dependency management
  • MongoDB for persistence
  • Redis for cache and inter-service messaging
  • protoc + ts-proto for gRPC code generation

Core Service Structure

src/
├─ index.ts                # entry: starts Express server
├─ app.ts                  # express app, middlewares, routes

├─ config/
│  ├─ env.ts               # environment configuration
│  └─ logger.ts            # centralized logger

├─ controllers/            # controllers (request handling)
│  ├─ user.controller.ts
│  ├─ report.controller.ts
│  └─ investigation.controller.ts

├─ routes/                 # express routes
│  ├─ user.routes.ts
│  ├─ report.routes.ts
│  └─ investigation.routes.ts

├─ models/                 # mongoose models
│  ├─ User.model.ts
│  ├─ Report.model.ts
│  └─ Investigation.model.ts

├─ services/               # business logic
│  ├─ user.service.ts
│  ├─ report.service.ts
│  └─ investigation.service.ts

├─ interfaces/             # service/domain contracts
│  ├─ IUserService.ts
│  ├─ IReportService.ts
│  ├─ IInvestigationService.ts
│  └─ IRepository.ts

├─ middlewares/
│  ├─ errorHandler.ts
│  └─ validateRequest.ts

├─ database/
│  ├─ mongo.connection.ts
│  └─ redis.client.ts

├─ grpc/                   # generated gRPC clients
│  ├─ auth.proto
│  ├─ auth_grpc_pb.ts
│  └─ auth_pb.ts

├─ utils/
│  ├─ schema.ts
│  ├─ time.ts
│  └─ apiResponse.ts

├─ types/                  # DTOs, enums, global contracts
│  ├─ user.ts              # IUser, IUserDTO, UserRole
│  ├─ report.ts            # IReport, ReportStatus
│  ├─ investigation.ts     # IInvestigation, InvestigationState
│  ├─ enums.ts             # ErrorCode, LogLevel
│  └─ index.d.ts           # Express global type extensions

├─ tests/
│  ├─ unit/
│  └─ e2e/

Auth Service (separate microservice)

The Auth Service is deployed independently.
It exposes gRPC endpoints for authentication and authorization logic.

gRPC Endpoints

RPC Method Maps To Endpoint Description
GenerateToken(LoginRequest) → TokenResponse /auth/login Authenticates user and returns JWT token.
ChangePassword(ChangePasswordRequest) → StatusResponse /auth/change-password Allows logged-in users to change their password.
ChangeAvatar(ChangeAvatarRequest) → StatusResponse /auth/change-avatar Updates user avatar and stores it in GCS.
CreateUser(CreateUserRequest) → UserResponse /admin/create-user Admin-only. Creates new user with role and credentials.
ResetPassword(ResetPasswordRequest) → StatusResponse /admin/reset-password Admin-only. Resets another user's password.
DeleteUser(DeleteUserRequest) → StatusResponse /admin/delete-user Admin-only. Deletes a user (not self).
GetUserById(UserRequest) → UserResponse /me Returns info about current authenticated user.

Inter-Service Communication

  • gRPC → synchronous calls (Core ↔ Auth).
    • Example: Core calls ValidateToken in Auth for protected routes.
  • Redis Pub/Sub → asynchronous events (e.g., user.created, session.expired).

Development Standards

  • TypeScript strict mode
  • ESLint + Prettier enforced
  • JSDoc required for public methods
  • Husky pre-commit hooks: lint, type-check, tests

Commit examples:

  • feat: add sceneLoop placeholder
  • fix: correct ESM import in index.ts
  • docs: add PROJECT_STRUCTURE.md
  • refactor(core): simplify World.tick order
  • test(e2e): add ws happy path
  • build: update tsconfig for declarations
  • ci: run lint and test on PR
  • revert: revert "feat: add ws"

Installation (Core Service)

  1. Install Node.js v22
  2. Install pnpm globally
    npm install -g pnpm
  3. Clone repository and install deps
    git clone <repository-url>
cd k12_BackEnd_Core
pnpm install
  4. Setup Husky
    pnpm dlx husky install
  5. Install protoc
    • macOS (Homebrew):
      brew install protobuf
  6. Generate gRPC code from proto files
    pnpm proto:gen
  7. Configure .env
    PORT=3000
MONGO_URI=mongodb://localhost:27017/k12
REDIS_URI=localhost
REDIS_PORT=6379
AUTH_GRPC_HOST=localhost
AUTH_GRPC_PORT=50051

Scripts

  • pnpm dev – run dev server
  • pnpm build – compile TypeScript
  • pnpm start – run compiled build
  • pnpm lint – lint code
  • pnpm proto:gen – generate gRPC stubs from proto files
  • pnpm test – run unit + e2e tests
  • pnpm run docs – generate disposable HTML docs into docs/ (ignored by git)

Documentation

Run pnpm run docs to build the temporary .doc-tmp/ bundle and output HTML documentation into docs/. The docs/ directory is ignored by git—regenerate it locally or in CI whenever you need fresh API docs.

Testing

  • Unit tests – services, utils
  • E2E tests – gRPC interactions + API routes