Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CodexaCP/DG_WEB/llms.txt

Use this file to discover all available pages before exploring further.

Every change to Dragon Guard WMS Web must follow these conventions before delivery. The frontend is an Angular 15 + PrimeNG 15 administrative application originating from the Sakai template — all production-facing surfaces must carry Dragon Guard and Grupo MAS branding. These rules govern architecture, service design, session handling, UX, and the boundary between web administration and handheld operational execution.

1. Architecture Rules

Dragon Guard WMS Web uses a standard Angular module architecture with lazy loading. All feature modules load under /dashboard. Do not reorganize the existing folder structure unless explicitly requested.

Lazy Loading

Every feature module is lazy-loaded under the /dashboard route. Register new modules in the router using loadChildren — never eagerly import feature modules into AppModule.

Module Extension

Extend existing modules instead of creating new patterns. Reuse receipts and shipments patterns before introducing new component structures.

Sakai Origin

The project originated from the Sakai template. Internal framework and library imports retain their original names. Only user-facing brand text is replaced.

Structure Stability

Do not reorganize the folder structure unless it is explicitly part of the task. Stability in structure reduces merge conflicts and onboarding friction.
Follow the existing Angular conventions already present in the codebase. When in doubt, match what is already there rather than introducing a new pattern.

2. Service Layer

All backend communication must go through WmsService or services located in src/app/core. Components must never make HTTP calls directly.
1

Route all HTTP through WmsService

Use WmsService or a dedicated core service for every backend call. Components call service methods — they never call HttpClient directly.
2

Use environment.apiUrl

Never hardcode a URL or base path in any file. Always reference environment.apiUrl so that builds targeting different environments resolve correctly.
3

Avoid endpoint duplication

Do not define the same endpoint in multiple service files. If an endpoint already exists in WmsService, call it — do not copy it into a feature service.
4

Respect API contracts

Do not modify payload structures casually. Do not assume backend behavior, and do not bypass backend validation. Prefer additive changes and always consider MAUI handheld compatibility.
// ✅ Correct — all HTTP through WmsService
constructor(private wms: WmsService) {}

loadReceipts() {
  this.wms.getReceipts(this.companyId).subscribe(data => {
    this.receipts = data;
  });
}

// ❌ Wrong — direct HTTP from a component
constructor(private http: HttpClient) {}

loadReceipts() {
  this.http.get(`${environment.apiUrl}/receipts`).subscribe(...);
}

3. Session and Authentication

1

Use AuthService for all auth operations

Login, logout, token retrieval, and active company management must go through AuthService. Components must never read the token directly from storage.
2

sessionStorage — not localStorage

The JWT token is stored in sessionStorage. Never move it to localStorage. Session-scoped storage prevents tokens from persisting across browser restarts.
3

JWT interceptor handles Authorization

The HTTP interceptor automatically attaches the Authorization: Bearer header to outgoing requests. Do not manually append the token in service or component code.
4

Respect active companyId

Every data request must include the active companyId from AuthService. Never allow cross-company data leakage by omitting or hardcoding the company context.
// ✅ Correct — reading company context through AuthService
constructor(private auth: AuthService, private wms: WmsService) {}

ngOnInit() {
  const companyId = this.auth.getActiveCompanyId();
  this.wms.getInventory(companyId).subscribe(...);
}

// ❌ Wrong — reading token directly from storage
const token = sessionStorage.getItem('token');

4. UX and Design

Dragon Guard WMS Web follows a professional administrative visual style for Grupo MAS. The palette uses a blue base, cyan accents, and orange or magenta highlights on light, clean backgrounds.

PrimeNG Components

Use PrimeNG components consistently throughout the application. Do not introduce third-party UI components or custom-built equivalents when a PrimeNG component already satisfies the need.

Tooltips for Sensitive Actions

Restricted or sensitive actions must show a PrimeNG pTooltip explaining why they are restricted. Do not silently disable buttons without user feedback.

No Demo UI in Production

Demo dashboards, demo menu entries, demo logos, and demo placeholder text must never appear in production routes. All user-facing surfaces carry Dragon Guard identity.

Server-Side Pagination

Use server-side pagination for all large dataset tables. Never load unbounded result sets into the browser. Always apply the active companyId filter.
Keep components focused and minimal. A component should do one thing well. Move business logic and API calls into services — components own only presentation and user interaction.

5. Operational Boundary

Dragon Guard WMS Web is an administrative application. The handheld MAUI application handles all operational execution on the warehouse floor.
The web frontend must NOT perform operational actions. Specifically:
  • Do not post receipts
  • Do not post shipments
  • Do not modify stock directly
These operations belong exclusively to the MAUI handheld application. Any change that crosses this boundary must be reviewed and explicitly approved.
The separation exists to enforce warehouse process integrity. Administrative screens cover configuration, oversight, reporting, and management — not physical inventory movement.

6. Error Handling

Display user-friendly, localized error messages for every failure case. Never expose raw backend error payloads or stack traces in the UI.
Show a toast or inline message describing which fields failed validation. Use the error body from the backend when safe and structured; otherwise show a generic validation message from the translation dictionary.
Redirect the user to the login screen and clear the session. Show a brief “Your session has expired” message before redirecting.
Show a generic “An unexpected error occurred. Please try again.” message. Log the error to the console for developer inspection but do not render the raw response in the UI.
Show a network error message indicating the service is temporarily unavailable. Provide a retry option where appropriate.
If companyId is not present in the session, prevent the data call and prompt the user to select or re-authenticate with a company. Do not send requests with a null or undefined company identifier.

7. Branding Validation Checklist

Run this checklist before every production release and after any layout change.
1

No visible 'Sakai' text

Confirm that no screen, menu, label, title, or footer visible to end users contains the word “Sakai”. Internal import names are exempt.
2

No demo menu entries

Verify that no demo or template menu entries appear in the sidebar or navigation. Production menus must reflect only Dragon Guard WMS modules.
3

No demo dashboard cards

Confirm that demo placeholder cards, widgets, or charts have been removed from the dashboard and replaced with live WMS data or intentional empty states.
4

Login screen uses Dragon Guard identity

The login page must display the Dragon Guard logo, application name, and Grupo MAS branding — not any Sakai or PrimeTek placeholder assets.
5

Sidebar, header, footer, browser title, favicon

Each surface must carry Dragon Guard identity. Check the browser tab title and favicon in addition to in-page elements.
6

Public text matches Dragon Guard and Grupo MAS branding

All publicly visible text — marketing, descriptions, copyright lines — must reference Dragon Guard and Grupo MAS, not the template origin.
When performing branding cleanup, make targeted replacements in template and asset files only. Do not run a broad search-and-replace across the codebase — it will break PrimeNG and Sakai framework imports that legitimately contain those strings.
After branding changes, validate: routing, menus, layout, login, dashboard, footer, browser title, and favicon.

8. Testing and Validation

Before delivering any change, the following checks are mandatory.
1

Build must pass

Run npm run build and confirm it completes without errors. A failing build is never acceptable for delivery.
npm run build
2

Login flow

Verify that login, token storage in sessionStorage, company selection, and redirect to dashboard all work correctly.
3

Dashboard and menu/sidebar

Confirm the dashboard loads with real data, no demo content is visible, and the sidebar menu reflects the current user’s permissions.
4

Changed module

Exercise the specific module you modified: list view, detail/form view, save, cancel, and any restricted actions.
5

API integration

Open the browser network tab and confirm that API calls use the correct environment.apiUrl base, include the JWT header, and carry the active companyId.
6

i18n text and branding

Switch the UI language and confirm all labels, tooltips, toasts, and dialog headers update. Confirm no Sakai or demo text is visible.
7

Restricted actions and tooltips

Trigger any restricted action and confirm the tooltip appears with the correct explanation. Confirm the action is blocked in the service layer.

9. What NOT To Do

The following actions are prohibited in Dragon Guard WMS Web:
  • Do not expose Sakai demo routes in production builds
  • Do not introduce new UI patterns without justification and alignment with existing conventions
  • Do not bypass the existing service layer architecture
  • Do not mix responsibilities between modules (keep feature boundaries clean)
  • Do not perform broad, unsafe search-and-replace branding operations that could break imports or PrimeNG dependencies
  • Do not call HttpClient directly from components
  • Do not hardcode API URLs — always use environment.apiUrl
  • Do not store the JWT token in localStorage
  • Do not read the token directly from storage in a component
  • Do not expose raw backend error messages or stack traces in the UI
  • Do not post receipts, post shipments, or modify stock from the web frontend
  • Do not send requests without the active companyId
  • Do not deliver a change without a passing npm run build

Build docs developers (and LLMs) love