Nhà Cộng

Documentation Center

System Guide

Project Overview

UP: 07/04/2026
AI MODERATOR
~15 MINS

PROJECT_CONTEXT.md — Nhà Cộng

Auto-generated by Antigravity on 2026-02-26. Update when the stack changes.

Overview

Nhà Cộng is a Vietnamese property rental management SaaS platform.
It allows landlords (chủ nhà), residents (cư dân), and collaborators (CTV) to manage rooms, buildings, contracts, invoices, payments, community discussions, asset tracking, and more.

  • Domains:
    DOCUMENTATION CODE
    nhacong.com.vn
    (production) /
    DOCUMENTATION CODE
    nc.thigio.com
    (staging)
  • Version:
    DOCUMENTATION CODE
    0.1.5
    (in
    DOCUMENTATION CODE
    version.txt
    ,
    DOCUMENTATION CODE
    package.json
    )
  • Registry: GitHub Container Registry (GHCR) —
    DOCUMENTATION CODE
    ghcr.io/xonevn-ai/nhacong-be
    /
    DOCUMENTATION CODE
    nhacong-fe

Tech Stack

Backend (
DOCUMENTATION CODE
/backend
)

ConcernTool / VersionEvidence
LanguageTypeScript 5
DOCUMENTATION CODE
backend/package.json
devDeps
RuntimeNode.js (LTS)
DOCUMENTATION CODE
backend/Dockerfile
FrameworkNestJS 10
DOCUMENTATION CODE
@nestjs/core ^10.4
ORMTypeORM 0.3
DOCUMENTATION CODE
@nestjs/typeorm ^11
,
DOCUMENTATION CODE
typeorm ^0.3.28
DatabaseMySQL 8.0
DOCUMENTATION CODE
docker-compose.yml
,
DOCUMENTATION CODE
mysql2 ^3
AuthJWT + Passport + Google OAuth
DOCUMENTATION CODE
@nestjs/jwt
,
DOCUMENTATION CODE
passport-jwt
,
DOCUMENTATION CODE
google-auth-library
WebSocketsSocket.IO 4
DOCUMENTATION CODE
@nestjs/websockets
,
DOCUMENTATION CODE
socket.io ^4.8
Scheduler
DOCUMENTATION CODE
@nestjs/schedule
+
DOCUMENTATION CODE
node-cron
DOCUMENTATION CODE
package.json
API DocsSwagger / OpenAPI
DOCUMENTATION CODE
@nestjs/swagger ^7
,
DOCUMENTATION CODE
/docs
route
File UploadMulter + local/S3
DOCUMENTATION CODE
multer ^2
,
DOCUMENTATION CODE
@aws-sdk/client-s3
EmailNodemailer + Resend
DOCUMENTATION CODE
nodemailer ^7
,
DOCUMENTATION CODE
RESEND_API_KEY
env
PaymentVNPay
DOCUMENTATION CODE
VNPAY_*
env vars
MessagingZalo / ZNS
DOCUMENTATION CODE
ZALO_*
env vars
PDFpdf-lib
DOCUMENTATION CODE
pdf-lib ^1.17.1
LoggingWinston (via
DOCUMENTATION CODE
nest-winston
)
DOCUMENTATION CODE
main.ts
→
DOCUMENTATION CODE
WinstonModule
Validationclass-validator + class-transformer
DOCUMENTATION CODE
package.json
,
DOCUMENTATION CODE
ValidationPipe
in
DOCUMENTATION CODE
main.ts
Caching
DOCUMENTATION CODE
cache-manager
+
DOCUMENTATION CODE
@nestjs/cache-manager
DOCUMENTATION CODE
package.json
Rate limiting
DOCUMENTATION CODE
@nestjs/throttler
DOCUMENTATION CODE
package.json
TestingJest 29 + Supertest
DOCUMENTATION CODE
package.json
jest section
SecurityHelmet, compression, cookie-parser
DOCUMENTATION CODE
main.ts

Frontend (
DOCUMENTATION CODE
/frontend
)

ConcernTool / VersionEvidence
LanguageTypeScript 5
DOCUMENTATION CODE
frontend/package.json
devDeps
FrameworkNext.js 16 (standalone output)
DOCUMENTATION CODE
package.json
DOCUMENTATION CODE
next ^16.1.6
UI LibraryReact 19
DOCUMENTATION CODE
react ^19.2.3
Component LibraryAnt Design 6
DOCUMENTATION CODE
antd ^6.2.0
StylingTailwindCSS v4 + PostCSS
DOCUMENTATION CODE
tailwindcss ^4
,
DOCUMENTATION CODE
postcss.config.mjs
StateZustand 5
DOCUMENTATION CODE
zustand ^5.0.10
Formsreact-hook-form 7
DOCUMENTATION CODE
package.json
ChartRecharts +
DOCUMENTATION CODE
@ant-design/charts
DOCUMENTATION CODE
package.json
MapsLeaflet + react-leaflet
DOCUMENTATION CODE
package.json
WebSocketssocket.io-client 4
DOCUMENTATION CODE
package.json
Rich Textsuneditor-react
DOCUMENTATION CODE
package.json
Toastreact-hot-toast + react-toastify
DOCUMENTATION CODE
package.json
E2E TestingPlaywright
DOCUMENTATION CODE
playwright.config.ts
,
DOCUMENTATION CODE
@playwright/test
Build outputNext.js standalone
DOCUMENTATION CODE
scripts/prepare-standalone.js

Infrastructure

ConcernToolEvidence
ContainerizationDocker (multi-stage)
DOCUMENTATION CODE
backend/Dockerfile
,
DOCUMENTATION CODE
frontend/Dockerfile
OrchestrationDocker Compose
DOCUMENTATION CODE
docker-compose.yml
,
DOCUMENTATION CODE
docker-compose.staging.yml
Reverse ProxyNginx Proxy Manager
DOCUMENTATION CODE
docker-compose.yml
service
DOCUMENTATION CODE
nginx-proxy-manager
DB AdminphpMyAdmin
DOCUMENTATION CODE
docker-compose.yml
port 8080
StorageLocal fs (default) or S3/Spaces
DOCUMENTATION CODE
STORAGE_TYPE
env
CloudDigitalOcean Droplet
DOCUMENTATION CODE
deploy.yml
SSH to
DOCUMENTATION CODE
DO_HOST
CI/CDGitHub Actions
DOCUMENTATION CODE
.github/workflows/deploy.yml
Image RegistryGHCR
DOCUMENTATION CODE
ghcr.io/xonevn-ai/nhacong-*
Cloud DeployRender (backend alt)
DOCUMENTATION CODE
backend/render.yaml

Repo Layout

DOCUMENTATION CODE
prj/
├── backend/                  # NestJS API service
│   ├── src/
│   │   ├── main.ts           # Bootstrap: Swagger, CORS, global pipes/filters
│   │   ├── app.module.ts     # Root module
│   │   ├── common/           # Shared: filters, guards, decorators, adapters
│   │   ├── config/           # ConfigService configs (logger, database, etc.)
│   │   ├── database/         # TypeORM data-source, migrations, seeds
│   │   ├── modules/          # 74 domain feature modules (see below)
│   │   ├── upload/           # File upload module
│   │   └── utils/            # Utility helpers
│   ├── .eslintrc.js
│   ├── .prettierrc
│   ├── tsconfig.json
│   └── Dockerfile / Dockerfile.dev
│
├── frontend/                 # Next.js app
│   ├── src/
│   │   ├── app/              # Next.js App Router pages
│   │   ├── components/       # Shared UI components
│   │   ├── features/         # Feature-specific component groups
│   │   ├── hooks/            # Custom React hooks
│   │   ├── services/         # API service layer (axios calls)
│   │   ├── type/             # Global TypeScript type definitions
│   │   ├── utils/            # Frontend utilities
│   │   ├── contexts/         # React context providers
│   │   ├── config/           # Frontend config constants
│   │   ├── lib/              # Library wrappers
│   │   └── theme/            # Ant Design / theme config
│   ├── e2e/                  # Playwright tests
│   ├── public/               # Static assets
│   ├── .prettierrc
│   ├── tsconfig.json
│   └── Dockerfile / Dockerfile.dev
│
├── docker-compose.yml         # Production stack
├── docker-compose.staging.yml # Staging stack (ports offset +50/+1)
├── build-deploy.sh            # Manual deploy helper
├── version.txt                # App version string
└── .github/workflows/
    └── deploy.yml             # CI: build → GHCR → SSH deploy

Key Backend Modules (74 total under
DOCUMENTATION CODE
backend/src/modules/
)

DOCUMENTATION CODE
auth
,
DOCUMENTATION CODE
users
,
DOCUMENTATION CODE
apartment
,
DOCUMENTATION CODE
building
,
DOCUMENTATION CODE
floors
,
DOCUMENTATION CODE
bed
,
DOCUMENTATION CODE
contracts
,
DOCUMENTATION CODE
deposits
,
DOCUMENTATION CODE
invoice
,
DOCUMENTATION CODE
payment
,
DOCUMENTATION CODE
wallet
,
DOCUMENTATION CODE
thu-chi
(income/expense),
DOCUMENTATION CODE
meter-reading
,
DOCUMENTATION CODE
tasks
,
DOCUMENTATION CODE
asset
,
DOCUMENTATION CODE
notifications
,
DOCUMENTATION CODE
conversations
,
DOCUMENTATION CODE
community-discussions
,
DOCUMENTATION CODE
marketplace
,
DOCUMENTATION CODE
ctv-*
(collaborator),
DOCUMENTATION CODE
zalo
,
DOCUMENTATION CODE
zalo-accounts
,
DOCUMENTATION CODE
kyc
,
DOCUMENTATION CODE
reports
,
DOCUMENTATION CODE
admin
,
DOCUMENTATION CODE
admin-dashboard
,
DOCUMENTATION CODE
scheduler
, and more.

Key Scripts

Backend (
DOCUMENTATION CODE
cd backend
)

DOCUMENTATION CODE
npm run start:dev       # Development mode with watch
npm run build           # Compile TypeScript
npm run start:prod      # Run compiled dist/main.js
npm run lint            # ESLint + auto-fix
npm run format          # Prettier format
npm run test            # Jest unit tests
npm run test:cov        # Coverage report
npm run migration:generate  # Generate new TypeORM migration
npm run migration:run       # Run pending migrations
npm run migration:revert    # Revert last migration
npm run seed            # Seed the database
npm run db:init         # Initialize DB schema

Frontend (
DOCUMENTATION CODE
cd frontend
)

DOCUMENTATION CODE
npm run dev             # Next.js dev server on port 3001
npm run build           # Production build (+ postbuild standalone copy)
npm run start           # Serve standalone build
npm run format          # Prettier
npm run lint            # Next.js lint
npm run test:e2e        # Playwright E2E tests

Run Book

Local Development (Docker preferred)

DOCUMENTATION CODE
# Start all services (backend, frontend, MySQL, Nginx, phpMyAdmin)
docker compose up -d

# Or develop individually
cd backend && npm install && npm run start:dev   # API on :5000
cd frontend && npm install && npm run dev        # UI on :3001

Environment files:

DOCUMENTATION CODE
backend/.env
and
DOCUMENTATION CODE
frontend/.env
(copy from
DOCUMENTATION CODE
.env.example
).

Staging

DOCUMENTATION CODE
docker compose -p nhacong-staging -f docker-compose.staging.yml up -d
# Backend on :5050, DB on :3307

Test / Lint / Format

DOCUMENTATION CODE
# Backend
cd backend
npm run test          # Jest unit tests (*.spec.ts in src/)
npm run test:e2e      # Jest e2e (test/jest-e2e.json)
npm run lint          # ESLint fix
npm run format        # Prettier write

# Frontend
cd frontend
npm run test:e2e      # Playwright
npm run lint          # next lint
npm run format        # Prettier write

Architecture

Backend — NestJS Module-First (feature-module layered)

Each domain module follows a consistent structure:

DOCUMENTATION CODE
modules/<domain>/
  ├── <domain>.module.ts      # NestJS module declaration
  ├── <domain>.controller.ts  # REST controller (decorators, guards)
  ├── <domain>.service.ts     # Business logic
  ├── <domain>.entity.ts      # TypeORM entity / table
  ├── dto/                    # Data Transfer Objects (class-validator)
  └── (optional) <domain>.gateway.ts  # WebSocket gateway
  • Global prefix:
    DOCUMENTATION CODE
    /api
  • Swagger docs:
    DOCUMENTATION CODE
    /docs
  • Health check:
    DOCUMENTATION CODE
    /api/health
  • Global pipes:
    DOCUMENTATION CODE
    ValidationPipe({ whitelist: true, transform: true })
  • Global filters:
    DOCUMENTATION CODE
    AllExceptionsFilter
  • WebSocket adapter:
    DOCUMENTATION CODE
    AuthenticatedSocketAdapter

Frontend — Next.js App Router + Feature Folders

  • Pages in
    DOCUMENTATION CODE
    src/app/
    using App Router conventions
  • Shared UI in
    DOCUMENTATION CODE
    src/components/
  • Domain UI in
    DOCUMENTATION CODE
    src/features/
  • API calls in
    DOCUMENTATION CODE
    src/services/
    (axios-based service modules)
  • Types in
    DOCUMENTATION CODE
    src/type/
  • Global state in Zustand stores

Conventions

Formatting

LocationRule
Backend prettier
DOCUMENTATION CODE
singleQuote: true
,
DOCUMENTATION CODE
trailingComma: "all"
Frontend prettier
DOCUMENTATION CODE
singleQuote: false
,
DOCUMENTATION CODE
semi: true
,
DOCUMENTATION CODE
trailingComma: "es5"
,
DOCUMENTATION CODE
printWidth: 100
Frontend editorconfigCharset utf-8, LF, 2-space indent

Naming

ItemConventionExample
Backend files
DOCUMENTATION CODE
kebab-case.type.ts
DOCUMENTATION CODE
auth.service.ts
,
DOCUMENTATION CODE
create-user.dto.ts
NestJS classes
DOCUMENTATION CODE
PascalCase
DOCUMENTATION CODE
AuthService
,
DOCUMENTATION CODE
CreateUserDto
Backend module dirs
DOCUMENTATION CODE
kebab-case
DOCUMENTATION CODE
ctv-commissions/
,
DOCUMENTATION CODE
service-providers/
Frontend pagesNext.js App Router dirs
DOCUMENTATION CODE
app/(landlord)/rooms/page.tsx
Frontend components
DOCUMENTATION CODE
PascalCase.tsx
DOCUMENTATION CODE
ApartmentCard.tsx
Frontend services
DOCUMENTATION CODE
kebab-case.service.ts
or
DOCUMENTATION CODE
*.service.ts
DOCUMENTATION CODE
auth.service.ts
API endpointsREST
DOCUMENTATION CODE
/api/{resource}
kebab-case
DOCUMENTATION CODE
/api/service-providers
Env vars
DOCUMENTATION CODE
SCREAMING_SNAKE_CASE
DOCUMENTATION CODE
DB_HOST
,
DOCUMENTATION CODE
JWT_SECRET

Error Handling

  • Backend uses
    DOCUMENTATION CODE
    AllExceptionsFilter
    (
    DOCUMENTATION CODE
    common/filters/http-exception.filter.ts
    ) for consistent error shape
  • Use NestJS built-in HTTP exceptions (
    DOCUMENTATION CODE
    NotFoundException
    ,
    DOCUMENTATION CODE
    UnauthorizedException
    , etc.)
  • Catch-and-log patterns in
    DOCUMENTATION CODE
    main.ts
    for graceful startup failures

Logging

  • Winston via
    DOCUMENTATION CODE
    nest-winston
    (configured in
    DOCUMENTATION CODE
    config/logger.config.ts
    )
  • DOCUMENTATION CODE
    Logger
    from
    DOCUMENTATION CODE
    @nestjs/common
    used for per-class logging
  • Frontend uses
    DOCUMENTATION CODE
    console.*
    (no logging framework detected)

API Design

  • RESTful CRUD endpoints per module
  • JWT Bearer auth (
    DOCUMENTATION CODE
    Authorization: Bearer <token>
    )
  • Google OAuth flow available
  • Swagger decorators (
    DOCUMENTATION CODE
    @ApiTags
    ,
    DOCUMENTATION CODE
    @ApiBearerAuth
    ,
    DOCUMENTATION CODE
    @ApiOperation
    ) on controllers
  • DTOs use
    DOCUMENTATION CODE
    class-validator
    decorators

TypeScript Strictness

LocationStrict mode
BackendRelaxed —
DOCUMENTATION CODE
strictNullChecks: false
,
DOCUMENTATION CODE
noImplicitAny: false
FrontendFull strict mode —
DOCUMENTATION CODE
strict: true

Do ✅ and Do Not ❌

Do ✅Do Not ❌
Follow module folder pattern for new domainsDo not place business logic in controllers
Add DTOs with class-validator decoratorsDo not bypass
DOCUMENTATION CODE
ValidationPipe
Use TypeORM entities with migrationsDo not enable
DOCUMENTATION CODE
DB_SYNCHRONIZE=true
in production
Use Swagger decorators on new endpointsDo not skip
DOCUMENTATION CODE
@ApiTags
/
DOCUMENTATION CODE
@ApiBearerAuth
Use
DOCUMENTATION CODE
Logger
from
DOCUMENTATION CODE
@nestjs/common
Do not use raw
DOCUMENTATION CODE
console.log
in backend
Throw NestJS HTTP exceptions in servicesDo not let unhandled errors escape
Use
DOCUMENTATION CODE
src/services/
for all API calls in frontend		Do not call
DOCUMENTATION CODE
fetch
/
DOCUMENTATION CODE
axios
directly in components
Run
DOCUMENTATION CODE
npm run format
+
DOCUMENTATION CODE
npm run lint
before commit		Do not commit unformatted code
Copy
DOCUMENTATION CODE
.env.example
to
DOCUMENTATION CODE
.env
locally		Do not commit
DOCUMENTATION CODE
.env
with real secrets
Use separate staging compose file for staging testsDo not use production ports for staging

Contribution Checklist

Before opening a PR:

  • Created/updated the NestJS module (module, controller, service, entity, DTOs)
  • Added or updated migration for schema changes
  • Ran
    DOCUMENTATION CODE
    npm run format
    in the changed workspace
  • Ran
    DOCUMENTATION CODE
    npm run lint
    and resolved errors
  • Ran
    DOCUMENTATION CODE
    npm run test
    in backend (zero failing unit tests)
  • Swagger docs updated if new endpoint added
  • No secrets committed (check
    DOCUMENTATION CODE
    .env
    is in
    DOCUMENTATION CODE
    .gitignore
    )
  • Docker-compose files unchanged unless infra change is intended
  • Branch pushed to
    DOCUMENTATION CODE
    staging
    for staging deploy; to
    DOCUMENTATION CODE
    main
    for production
Next Page
System Administration (Admin)