lcbp3/docs/Markdown/FullStackJS_Guidelines01.md

FullStackJS Development Guidelines

🧠 General Philosophy

Unified best practices for NestJS Backend, NextJS Frontend, and Bootstrap-based UI/UX development in TypeScript environments.
Focus on clarity, maintainability, consistency, and accessibility across the entire stack.

---

⚙️ TypeScript General Guidelines

Basic Principles

• Use English for all code and documentation.
• Explicitly type all variables, parameters, and return values.
• Avoid any; create custom types or interfaces.
• Use JSDoc for public classes and methods.
• Export only one main symbol per file.
• Avoid blank lines within functions.

Naming Conventions

Entity	Convention	Example
Classes	PascalCase	UserService
Variables & Functions	camelCase	getUserInfo
Files & Folders	kebab-case	user-service.ts
Environment Variables	UPPERCASE	DATABASE_URL
Booleans	Verb + Noun	isActive, canDelete, hasPermission

Use full words — no abbreviations — except for standard ones (API, URL, req, res, err, ctx).

---

🧩 Functions

• Write short, single-purpose functions (<20 lines).
• Use early returns to reduce nesting.
• Use map, filter, reduce instead of loops when suitable.
• Prefer arrow functions for short logic, named functions otherwise.
• Use default parameters over null checks.
• Group multiple parameters into a single object (RO-RO pattern).
• Return typed objects, not primitives.
• Maintain a single abstraction level per function.

---

🧱 Data Handling

• Encapsulate data in composite types.
• Use immutability with readonly and as const.
• Perform validations in classes or DTOs, not within business functions.
• Always validate data using typed DTOs.

---

🧰 Classes

• Follow SOLID principles.
• Prefer composition over inheritance.
• Define interfaces for contracts.
• Keep classes focused and small (<200 lines, <10 methods, <10 properties).

---

🚨 Error Handling

• Use exceptions for unexpected errors.
• Catch only to fix or add context; otherwise, use global error handlers.
• Always provide meaningful error messages.

---

🧪 Testing (General)

• Use the Arrange–Act–Assert pattern.
• Use descriptive test variable names (inputData, expectedOutput).
• Write unit tests for all public methods.
• Mock external dependencies.
• Add acceptance tests per module using Given–When–Then.

---

🏗️ Backend (NestJS)

Principles

• Modular architecture:
  • One module per domain.
  • Controller → Service → Model structure.
• DTOs validated with class-validator.
• Use MikroORM or equivalent for persistence.
• Encapsulate reusable code in a common module (@app/common):
  • Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators.

Core Functionalities

• Global filters for exception handling.
• Middlewares for request handling.
• Guards for permissions and RBAC.
• Interceptors for response transformation and logging.

Testing

• Use Jest for testing.
• Test each controller and service.
• Add admin/test endpoint as a smoke test.

---

🖥️ Frontend (NextJS / React)

Developer Profile

Senior-level TypeScript + React/NextJS engineer.
Expert in TailwindCSS, Shadcn/UI, and Radix for UI development.

Code Implementation Guidelines

• Use early returns for clarity.
• Always style with TailwindCSS classes.
• Prefer class: conditional syntax over ternary operators.
• Use const arrow functions for components and handlers.
• Event handlers start with handle... (e.g., handleClick, handleSubmit).
• Include accessibility attributes:
  tabIndex="0", aria-label, onKeyDown, etc.
• Ensure all code is complete, tested, and DRY.
• Always import required modules explicitly.

UI/UX with React

• Use semantic HTML.
• Apply responsive Tailwind classes.
• Maintain visual hierarchy with typography and spacing.
• Use Shadcn components for consistent UI.
• Keep components small and focused.

---

🎨 UI/UX (Bootstrap Integration)

Key Principles

• Use Bootstrap 5+ for responsive design and consistent UI.
• Focus on maintainability, readability, and accessibility.
• Use clear and descriptive class names.

Bootstrap Usage

• Structure layout with container, row, col.
• Use built-in components (buttons, modals, alerts, etc.) instead of custom CSS.
• Apply utility classes for quick styling (spacing, colors, text, etc.).
• Ensure ARIA compliance and semantic markup.

Form Validation & Errors

• Use Bootstrap’s built-in validation states.
• Show errors with alert components.
• Include labels, placeholders, and feedback messages.

Dependencies

• Bootstrap (latest CSS + JS)
• Optionally jQuery (for legacy interactive components)

Bootstrap-Specific Guidelines

• Customize Bootstrap via Sass variables and mixins.
• Use responsive visibility utilities.
• Avoid overriding Bootstrap; extend it.
• Follow official documentation for examples.

Performance Optimization

• Include only necessary Bootstrap modules.
• Use CDN for assets and caching.
• Optimize images and assets for mobile.

Key Conventions

1. Follow Bootstrap’s naming and structure.
2. Prioritize responsiveness and accessibility.
3. Keep the file structure organized and modular.

---

🔗 Full Stack Integration Guidelines

Aspect	Backend (NestJS)	Frontend (NextJS)	UI Layer (Bootstrap/Tailwind)
API	REST / GraphQL Controllers	API hooks via fetch/axios	Components consuming data
Validation	class-validator DTOs	zod / form-level validation	Bootstrap validation feedback
Auth	Guards, JWT	NextAuth / cookies	Auth UI states
Errors	Global filters	Toasts / modals	Alerts / feedback
Testing	Jest (unit/e2e)	Vitest / Playwright	Visual regression
Styles	Scoped modules	Tailwind / Shadcn	Bootstrap utilities
Accessibility	Guards + filters	ARIA attributes	Semantic HTML

---

✅ Final Notes

• Use a shared types package (@types/shared) for consistent interfaces.
• Document your modules and APIs.
• Run lint, type-check, and tests before commit.
• Use Prettier + ESLint for consistent formatting.
• Prefer clarity over cleverness — readable code wins.

---

🗂️ DMS-Specific Conventions (Document Management System)

This section extends the general FullStackJS guidelines for projects similar to np‑dms.work, focusing on document approval workflows (RFA, Drawing, Contract, Revision, Transmittal, Report).

🧱 Backend Domain Modules

Use modular domain structure per document type:

src/
 ├─ modules/
 │   ├─ rfas/
 │   ├─ drawings/
 │   ├─ contracts/
 │   ├─ transmittals/
 │   ├─ audit-log/
 │   ├─ users/
 │   └─ common/

Naming Convention

Entity	Example
Table	rfa_revisions, drawing_contracts
DTO	CreateRfaDto, UpdateContractDto
Controller	rfas.controller.ts
Service	rfas.service.ts

---

🧩 RBAC & Permission Control

Use decorators to enforce access rights:

@RequirePermission('rfa.update')
@Put(':id')
updateRFA(@Param('id') id: string) {
  return this.rfaService.update(id);
}

Roles

• Admin: Full access to all modules.
• Editor: Modify data within assigned modules.
• Viewer: Read‑only access.

Permissions

• rfa.create, rfa.update, rfa.delete, rfa.view
• drawing.upload, drawing.map, drawing.view
• contract.assign, contract.view

Seed mapping between roles and permissions via seeder scripts.

---

🧾 AuditLog Standard

Log all CRUD and mapping operations:

Field	Description
actor_id	user performing the action
module_name	e.g. rfa, drawing
action	create, update, delete, map
target_id	primary id of the record
timestamp	UTC timestamp
description	contextual note

Example implementation:

await this.auditLogService.log({
  actorId: user.id,
  moduleName: 'rfa',
  action: 'update',
  targetId: rfa.id,
  description: `Updated revision ${rev}`,
});

---

📂 File Handling

File Upload Standard

• Upload path: /storage/{year}/{month}/
• File naming: {drawing_code}_{revision}_{timestamp}.pdf
• Allowed types: pdf, dwg, docx, xlsx, zip
• Max size: 50 MB
• Store outside webroot.
• Serve via secure endpoint /files/:id/download.

Access Control

Each file download must verify user permission (hasPermission('drawing.view')).

---

📊 Reporting & Exports

Report	Description
Report A	RFA → Drawings → All Drawing Revisions
Report B	RFA Revision Timeline vs Drawing Revision
Dashboard KPI	RFAs, Drawings, Revisions, Transmittals summary

Export Rules

• Export formats: CSV, Excel, PDF.
• Provide print view.
• Include source entity link (e.g., /rfas/:id).

---

🧮 Frontend: DataTable & Form Patterns

DataTable (Server‑Side)

• Endpoint: /api/{module}?page=1&pageSize=20
• Must support: pagination, sorting, search, filters.
• Always display latest revision inline (for RFA/Drawing).

Form Standards

• Dependent dropdowns:
  • Contract → Subcategory
  • RFA → Related Drawing
• File upload: preview + validation.
• Submit via API with toast feedback.

---

🧭 Dashboard & Activity Feed

Dashboard Cards

• Show latest RFA, Drawing, Transmittal, KPI summary.
• Include quick links to modules.

Activity Feed

• Display recent AuditLog actions (10 latest).

// Example response
[
  { user: 'admin', action: 'Updated RFA 023-Rev02', time: '2025‑11‑04T09:30Z' }
]

---

✅ Integration Summary

| Aspect | Backend | Frontend | Description | |:--|:--|:--| | File Handling | Secure storage, token check | Upload/Preview UI | Consistent standard path | | RBAC | RequirePermission guard | Hide/disable UI actions | Unified permission logic | | AuditLog | Persist actions | Show in dashboard | Traceable user activity | | Reports | Aggregation queries | Export + Print | Consistent data pipeline | | DataTables | Server‑side paging | Filter/Search UI | Scalable dataset management |

---

🧩 Recommended Enhancements

• ✅ Add deleted_at for soft delete + restore.
• ✅ Fulltext search + date filters.
• ✅ Background job for RFA deadline reminders.
• ✅ Optimize DB with indexes on rfa_id, drawing_id, contract_id.
• ✅ Periodic cleanup for unused file uploads.

---