refactor(core): remove legacy dummy services, reorganize navigation IA, and align project documentation with implemented architecture

Author: Diogo Ferraz

README.md

@@ -1,27 +1,44 @@
 # TaskManagementClient
 
-This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 18.2.11.
+Angular SPA for a Jira-style task management system, integrated with an existing .NET 8 backend.
 
-## Development server
+## Highlights
 
-Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The application will automatically reload if you change any of the source files.
+- OIDC authentication (Authorization Code + PKCE) against OpenIddict
+- Role-aware UX for `Administrator`, `ProjectManager`, and `User`
+- Real-time activity updates via SignalR
+- Project Kanban board with drag/drop and inline task editing
+- Dashboard, calendar, search/filters, admin tools, activity views, and settings
+- Preview mode support for frontend-only workflows
 
-## Code scaffolding
+## Tech Stack
 
-Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.
+- Angular 18 (standalone components)
+- PrimeNG UI
+- RxJS
+- SignalR JavaScript client
 
-## Build
+## Architecture
 
-Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory.
+- `src/app/core`: auth, api clients, config, layout, realtime, preferences
+- `src/app/features`: page-level feature components by domain
+- `src/app/shared`: shared module and reusable UI pieces
 
-## Running unit tests
+The SPA is API-contract-first: typed DTOs and clients are aligned with backend endpoints.
 
-Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).
+## Sidebar Information Architecture
 
-## Running end-to-end tests
+- Overview: Dashboard
+- Workspaces: Projects, Project Details, Project Members, Kanban
+- Delivery: All Tasks, My Tasks, Create Task
+- Activity: My Activity, Activity Log, Calendar, Search & Filters
+- Account: Profile & Security, Settings
+- Administration: Admin Dashboard
+- About: Project Docs
 
-Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To use this command, you need to first add a package that implements end-to-end testing capabilities.
+## Run
 
-## Further help
-
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+- Install dependencies: `npm install`
+- Development server: `npm start`
+- Build: `npm run build`
+- Tests: `npm test`

docs/SPA_ARCHITECTURE_PLAN.md

@@ -1,53 +1,78 @@
 # SPA Architecture Plan (Angular + .NET 8 API)
 
-## Architecture decisions
-- Use Angular standalone-first feature architecture (no new NgModules).
-- Keep clear boundaries: `core` (cross-cutting), `shared` (pure UI primitives), `features` (domain pages/use-cases).
-- Keep API contract strict by maintaining backend-aligned DTO/request models under `core/api/models`.
-- Use typed API clients per backend feature under `core/api/clients`.
-- Use route-level lazy loading for each feature page group.
-- Use Signals for local UI state and RxJS streams for async/server workflows.
-
-## Proposed folder structure
-- `src/app/core/config`: environment/config injection tokens.
-- `src/app/core/auth`: OIDC PKCE flow, auth facade, role extraction.
-- `src/app/core/http`: interceptors (auth bearer, problem-details mapping, retry policy).
-- `src/app/core/api`: typed models + API clients (projects, taskitems, activity, dashboard, users).
-- `src/app/core/realtime`: SignalR clients and event mappers.
-- `src/app/features/dashboard`: dashboard shell + summary cards + activity feed.
-- `src/app/features/kanban`: project board, drag/drop interactions, task update workflows.
-- `src/app/features/search`: cross-entity filters/search views.
-- `src/app/shared/ui`: reusable presentational components (cards, chips, loaders, empty states).
-- `src/app/shared/utils`: pure helpers/formatters with tests.
-
-## State strategy
-- Feature facades own page state and orchestration.
-- Keep state close to feature; avoid global store until needed.
-- Use explicit `load/error/empty` view models for each screen.
-- Use optimistic updates only where backend conflict risk is low; otherwise apply server-authoritative updates.
-
-## Routing and authorization
-- Public routes: login + auth callback.
-- Protected routes: dashboard, board, search.
-- Route data declares required capabilities; guard checks token roles.
-- UI capability helpers control action visibility but API remains final authority.
-
-## API contract alignment rules
-- No frontend-only enum/value inventions.
-- Patch payloads use omitted vs `null` semantics exactly as API contract defines.
-- Date query filters use ISO-8601 UTC.
-- ProblemDetails (`application/problem+json`) mapped to typed client errors.
-
-## Planned commit slices
-1. Foundation: typed API models/clients + environment/config plumbing.
-2. Auth: OIDC code+PKCE login/callback/logout + auth guard/interceptor.
-3. Dashboard: server summary + activity history + SignalR live feed.
-4. Kanban read model: project selector + grouped task columns from API.
-5. Kanban mutations: patch task status/assignee/due date with optimistic UX safeguards.
-6. Search/filter page: users/projects/tasks filters + pagination.
-7. Quality pass: unit tests for core clients/facades + component tests for key flows.
-8. Cleanup pass: remove legacy dummy services/components and dead CSS.
-
-## Backend gap found during alignment
-- `GET /api/projects/{id}` currently requires `CanManageProjects` policy, which excludes `User` role at authorization layer.
-- This appears to conflict with documented matrix intention where `User` should have scoped project read access.
+## Current architecture status
+- Angular standalone-first architecture is active (no feature NgModules used in runtime).
+- Clear boundaries are in place:
+  - `core`: auth, api clients/models, config, layout, realtime, preferences.
+  - `shared`: shared module + reusable cross-feature UI.
+  - `features`: page-level domain slices.
+- API contracts are typed and aligned under `core/api/models` and consumed through `core/api/clients`.
+- RxJS is used for async/server orchestration; Signals/computed are used for local/session/preferences state.
+
+## Implemented folder structure
+- `src/app/core/config`: app environment token + runtime config plumbing.
+- `src/app/core/auth`: OIDC PKCE auth service + guards (`auth`, `admin`, `managerOrAdmin`).
+- `src/app/core/http`: query param/url helpers and HTTP integration utilities.
+- `src/app/core/api`: typed DTOs + API clients (`projects`, `taskitems`, `activity`, `dashboard`, `users`).
+- `src/app/core/realtime`: SignalR hub integration for activity feed/log updates.
+- `src/app/core/preferences`: persisted app preferences service (density/date/notification/kanban defaults).
+- `src/app/features`: dashboard, projects, tasks, search, calendar, activity, profile, settings, docs, admin.
+
+## Routing and authorization (implemented)
+- Public routes:
+  - `/` (landing)
+  - `/login`
+  - `/callback`
+- Protected routes:
+  - dashboard/workspaces/delivery/activity/account/about.
+- Role-restricted routes:
+  - `/admin` -> `Administrator`.
+  - `/activity/log` -> `Administrator` or `ProjectManager`.
+
+## Sidebar information architecture (current)
+- Overview: Dashboard
+- Workspaces: All Projects, Project Details, Project Members, Create Project, Kanban
+- Delivery: All Tasks, My Tasks, Create Task
+- Activity: My Activity, Activity Log, Calendar, Search & Filters
+- Account: Profile & Security, Settings
+- Administration: Admin Dashboard
+- About: Project Docs
+
+## Core feature status
+- Auth foundation:
+  - OIDC Authorization Code + PKCE, callback handling, guarded routes.
+- Dashboard:
+  - Summary KPIs + activity history + SignalR live updates + preview fallback.
+- Kanban:
+  - Project picker, grouped status columns, drag/drop, create/edit dialogs, optimistic patch flows.
+- Search & filters:
+  - Cross-entity filtering flows aligned with current API clients.
+- Project tools:
+  - All Projects, Project Details, Project Members.
+- Task tools:
+  - All Tasks, My Tasks, Create Task.
+- Activity tools:
+  - My Activity (personal timeline) + Activity Log (admin/pm audit).
+- Account:
+  - Profile & Security, Settings (persisted app preferences).
+
+## Contract alignment rules (enforced)
+- Frontend uses backend enums/contracts from typed models (no ad-hoc enum invention).
+- Patch semantics preserve omitted vs `null` behavior.
+- Date values sent to API follow ISO conventions.
+- Problem Details responses are surfaced consistently at UI layer.
+
+## Quality and cleanup status
+- Legacy scaffold artifacts removed:
+  - unused dummy services (`ProjectService`, `TaskItemService`, `LoginService`) and associated specs.
+  - empty unused feature modules (`projects.module.ts`, `task-item.module.ts`).
+- UI consistency pass completed across major pages:
+  - header card + kpi cards + main content card patterns.
+  - PrimeNG built-in table filter strategy on table-centric pages.
+
+## Known backend/API gaps worth addressing
+- Activity endpoint filtering:
+  - Current contract used by SPA does not expose server-side actor/type/date filters.
+  - Activity Log currently applies these filters client-side after fetching feed data.
+- Authorization matrix check:
+  - `GET /api/projects/{id}` policy should be verified against intended `User` read capabilities.

src/app/core/layout/component/app-menu/app-menu.component.ts

@@ -22,7 +22,7 @@ export class AppMenuComponent {
         items: [{ label: 'Dashboard', icon: 'pi pi-fw pi-home', routerLink: ['/dashboard'] }]
       },
       {
-        label: 'Projects',
+        label: 'Workspaces',
         items: [
           { label: 'All Projects', icon: 'pi pi-fw pi-list', routerLink: ['/projects'] },
           { label: 'Project Details', icon: 'pi pi-fw pi-folder-open', routerLink: ['/projects/details'] },
@@ -32,22 +32,32 @@ export class AppMenuComponent {
         ]
       },
       {
-        label: 'Tasks',
+        label: 'Delivery',
         items: [
           { label: 'All Tasks', icon: 'pi pi-fw pi-list', routerLink: ['/tasks'] },
           { label: 'My Tasks', icon: 'pi pi-fw pi-user', routerLink: ['/tasks/my-tasks'] },
           { label: 'Create Task', icon: 'pi pi-fw pi-plus', routerLink: ['/tasks/create'] }
         ]
       },
       {
-        label: 'Insights',
+        label: 'Activity',
         items: [
           { label: 'My Activity', icon: 'pi pi-fw pi-history', routerLink: ['/activity/my'] },
           { label: 'Activity Log', icon: 'pi pi-fw pi-database', routerLink: ['/activity/log'], visible: this.authService.hasAnyRole(['Administrator', 'ProjectManager']) },
-          { label: 'Settings', icon: 'pi pi-fw pi-cog', routerLink: ['/settings'] },
-          { label: 'Profile & Security', icon: 'pi pi-fw pi-user-edit', routerLink: ['/profile'] },
-          { label: 'Search & Filters', icon: 'pi pi-fw pi-search', routerLink: ['/search'] },
           { label: 'Calendar', icon: 'pi pi-fw pi-calendar', routerLink: ['/calendar'] },
+          { label: 'Search & Filters', icon: 'pi pi-fw pi-search', routerLink: ['/search'] }
+        ]
+      },
+      {
+        label: 'Account',
+        items: [
+          { label: 'Profile & Security', icon: 'pi pi-fw pi-user-edit', routerLink: ['/profile'] },
+          { label: 'Settings', icon: 'pi pi-fw pi-cog', routerLink: ['/settings'] }
+        ]
+      },
+      {
+        label: 'About',
+        items: [
           { label: 'Project Docs', icon: 'pi pi-fw pi-book', routerLink: ['/docs'] }
         ]
       },

src/app/features/docs/components/project-docs/project-docs.component.html

@@ -18,7 +18,7 @@ <h2>Task Management Platform</h2>
     </div>
   </p-card>
 
-  <div class="docs-grid docs-grid--equal">
+  <div class="docs-grid docs-grid--equal docs-grid--two">
     <p-card header="Project Purpose" styleClass="docs-card">
       <p>
         Build a practical collaboration workspace where teams can plan, execute, and track work using boards,
@@ -44,7 +44,7 @@ <h2>Task Management Platform</h2>
     </p-card>
   </div>
 
-  <div class="docs-grid docs-grid--equal">
+  <div class="docs-grid docs-grid--equal docs-grid--three">
     <p-card header="Tech Stack" styleClass="docs-card">
       <ul class="docs-list">
         <li *ngFor="let item of techStack">{{ item }}</li>
@@ -63,4 +63,24 @@ <h2>Task Management Platform</h2>
       </ul>
     </p-card>
   </div>
+
+  <div class="docs-grid docs-grid--equal docs-grid--three">
+    <p-card header="Navigation Information Architecture" styleClass="docs-card">
+      <ul class="docs-list">
+        <li *ngFor="let item of navigationGroups">{{ item }}</li>
+      </ul>
+    </p-card>
+
+    <p-card header="Engineering Standards" styleClass="docs-card">
+      <ul class="docs-list">
+        <li *ngFor="let item of engineeringStandards">{{ item }}</li>
+      </ul>
+    </p-card>
+
+    <p-card header="Quality & Delivery" styleClass="docs-card">
+      <ul class="docs-list">
+        <li *ngFor="let item of qualityAndDelivery">{{ item }}</li>
+      </ul>
+    </p-card>
+  </div>
 </section>

src/app/features/docs/components/project-docs/project-docs.component.scss

@@ -58,12 +58,11 @@
   display: block;
 }
 
-.docs-grid.docs-grid--equal p-card:first-child,
-.docs-grid.docs-grid--equal p-card:nth-child(2) {
+.docs-grid.docs-grid--two p-card {
   grid-column: span 6;
 }
 
-.docs-grid.docs-grid--equal:last-of-type p-card {
+.docs-grid.docs-grid--three p-card {
   grid-column: span 4;
 }
 
@@ -99,7 +98,7 @@
 }
 
 @media (max-width: 1200px) {
-  .docs-grid.docs-grid--equal:last-of-type p-card {
+  .docs-grid.docs-grid--three p-card {
     grid-column: span 6;
   }
 }
@@ -114,9 +113,8 @@
     gap: 1rem;
   }
 
-  .docs-grid.docs-grid--equal p-card:first-child,
-  .docs-grid.docs-grid--equal p-card:nth-child(2),
-  .docs-grid.docs-grid--equal:last-of-type p-card {
+  .docs-grid.docs-grid--two p-card,
+  .docs-grid.docs-grid--three p-card {
     grid-column: auto;
   }
 }

src/app/features/docs/components/project-docs/project-docs.component.ts

@@ -21,9 +21,12 @@ export class ProjectDocsComponent {
 
   readonly highlights = [
     'Role-aware UI for Administrator / ProjectManager / User',
-    'Dashboard with summary counters and live feed',
-    'Kanban board with patch-based optimistic updates',
-    'Search & filtering across projects, users, and tasks'
+    'Dashboard with summary counters and real-time activity',
+    'Jira-style Kanban board with drag/drop and inline task editing',
+    'Project details, project members, and task calendar',
+    'Activity views: My Activity and Admin/PM Activity Log',
+    'Admin dashboard with user activation and CSV export',
+    'Settings page with persisted app preferences'
   ];
 
   readonly principles = [
@@ -32,4 +35,31 @@ export class ProjectDocsComponent {
     'Resilient UX by default: loading, empty, and degraded states are always visible.',
     'Incremental delivery through focused commits and maintainable architecture.'
   ];
+
+  readonly navigationGroups = [
+    'Overview: Dashboard',
+    'Workspaces: Projects, Project Details, Project Members, Kanban',
+    'Delivery: All Tasks, My Tasks, Create Task',
+    'Activity: My Activity, Activity Log, Calendar, Search & Filters',
+    'Account: Profile & Security, Settings',
+    'Administration: Admin Dashboard',
+    'About: Project Docs'
+  ];
+
+  readonly engineeringStandards = [
+    'Typed API client boundary under core/api with explicit DTO contracts.',
+    'Role-aware routing and UI behavior for Administrator, ProjectManager, and User.',
+    'OIDC Authorization Code + PKCE flow with guarded routes and secure callbacks.',
+    'SignalR event ingestion for real-time activity without polling fallback.',
+    'Problem Details-aligned error surfaces and resilient loading/empty/degraded states.',
+    'Consistent PrimeNG-based component strategy for long-term maintainability.'
+  ];
+
+  readonly qualityAndDelivery = [
+    'Incremental feature delivery with focused commit scopes and page-by-page hardening.',
+    'Standalone Angular feature components organized by domain responsibility.',
+    'Preview mode enables frontend validation while preserving production auth constraints.',
+    'Responsive behavior is considered first-class across dashboard, kanban, tables, and forms.',
+    'Build/test verification executed before closing implementation steps.'
+  ];
 }