Frontend Conventions: Angular Coding and Architecture
Coding, service layer, branding, UX, and validation rules for Dragon Guard WMS Web. Every contributor must follow these conventions before delivering any change.
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.
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.
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 WmsServiceconstructor(private wms: WmsService) {}loadReceipts() { this.wms.getReceipts(this.companyId).subscribe(data => { this.receipts = data; });}// ❌ Wrong — direct HTTP from a componentconstructor(private http: HttpClient) {}loadReceipts() { this.http.get(`${environment.apiUrl}/receipts`).subscribe(...);}
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.
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.
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.
Display user-friendly, localized error messages for every failure case. Never expose raw backend error payloads or stack traces in the UI.
400 — Validation Error
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.
401 — Unauthorized or Token Expired
Redirect the user to the login screen and clear the session. Show a brief “Your session has expired” message before redirecting.
500 — Server Error
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.
Backend Unavailable
Show a network error message indicating the service is temporarily unavailable. Provide a retry option where appropriate.
Missing Company Context
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.
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.
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.