How mchartt/ingegneriasoftwaretest works
1. Repository shape
- This is a monorepo with two independent runtime applications:
- smartdesk-backend: a Spring Boot REST API in Java 17.
- smartdesk-frontend: an Angular SPA in TypeScript.
- The frontend talks to the backend over HTTP, typically through /api-routed calls and environment/proxy configuration.
2. Backend as the system of record
- The backend owns all business rules and persistence.
- It uses a classic layered structure: controllers → services → repositories → JPA entities/models.
- DTOs and mappers sit between HTTP payloads and persistence models to keep API contracts separate from domain entities.
3. Backend API boundaries
- Controllers are grouped by audience/domain: auth, worker, host, technician, admin, plus shared areas like booking, space, desk, and profile.
- This suggests role-specific endpoints on top of shared core entities, rather than a generic CRUD API.
4. Core domain subsystems
- The main business areas are:
- Spaces and desks: coworking space hierarchy, rooms, desks, opening hours, amenity presets, closures.
- Bookings and waitlists: booking creation/query/cancellation/rescheduling and waitlist management.
- Tickets and maintenance: ticket lifecycle, technician assignment, comments/notes, and desk maintenance.
- Reviews: worker reviews and host-facing moderation/replies.
- Notifications: persistent notifications and real-time delivery.
- Administration: system logs, moderation, and administrative operations.
5. Security and identity
- Authentication is JWT-based, with a custom JWT filter in the Spring Security chain.
- The backend includes token lifecycle support such as refresh tokens and revoked tokens, indicating stateless access tokens with server-side invalidation support.
- Authorization is role-driven, matching the user personas in the app: worker, host, technician, admin.
6. Backend business services
- Services are split by capability, not by transport:
- booking/* handles booking rules, availability, cancellation, end-of-session logic, and waitlist.
- space/* and host/* manage space composition and ownership-related workflows.
- ticket/* manages lifecycle transitions, technician assignment, and messaging.
- notification/* handles storage and broadcast.
- security/* handles auth, tokens, and access control.
- This separation is important for the architecture diagram: controllers are thin, while services contain the real orchestration.
7. State and observer patterns in the backend
- Two explicit state machines appear in the codebase:
- Desk state: available, reserved, maintenance, pending inspection, decommissioned.
- Ticket state: open, in progress, verifying, resolved, closed.
- Booking-related flows also use an observer-style mechanism for events like waitlist updates and host cancellation notices.
- These patterns are not just academic: they are central to how mutable business objects change safely.
8. Persistence and data storage
- Persistence is via Spring Data JPA repositories over a relational DB.
- Local development uses H2, with a file-backed database in smartdesk-backend/data/; MySQL support is present in resources/config for alternative deployment.
- Bootstrap seeders populate initial users, spaces, bookings, tickets, and reviews, which makes the app usable immediately in dev mode.
9. Backend cross-cutting concerns
- Errors are normalized through a centralized exception hierarchy and REST exception handler.
- Validation utilities and policy classes enforce business constraints such as password strength, booking time rules, and text validation.
- There is also explicit support for Swagger/OpenAPI configuration, implying documented REST contracts.
10. Real-time and asynchronous user feedback
- Notifications are not only stored but also broadcast in real time, with a stream hub and broadcaster service plus SSE-related frontend utilities.
- This means the app has both a persistence path and a live-update path for notification events.
11. Frontend application structure
- The Angular app is organized by role-based feature areas:
- auth
- public
- worker
- host
- technician
- admin
- Shared UI lives in shared, while API-facing state and integrations live in core.
- Routing is split per role, which mirrors the backend’s authorization model.
12. Frontend integration layer
- core/services contains the API clients for bookings, auth, host, worker, technician, review, ticket, admin, notifications, etc.
- core/interceptors manage JWT attachment, refresh handling, and session expiry behavior.
- core/guards enforce route access based on authentication and role.
- This creates a clean boundary: UI pages do not talk to HTTP directly; they go through shared services and auth infrastructure.
13. Frontend state and UX patterns
- The frontend models the backend domain explicitly with TypeScript models for bookings, desks, spaces, tickets, notifications, reviews, users, and desk state variants.
- There is a fair amount of reusable shell/UI infrastructure: role shell, navbars, notification bell, modal/confirm components, toast container, ticket chat, status badges, and timeline/search widgets.
- Theme handling and viewport constraints are first-class, so layout responsiveness is part of the architecture.
14. How a request typically flows
- A user action in a role-specific Angular page calls a core service.
- The request passes through JWT/refresh interceptors.
- The backend controller receives it, delegates to a domain service, which validates rules and accesses repositories.
- The service updates JPA entities and, when relevant, emits notification/booking events.
- Results return as DTOs, often mapped from domain objects, and the frontend updates UI state or receives a live notification event.
15. Testing and maintainability signals
- Both halves are heavily tested: controller tests, service tests, integration flows, and frontend specs.
- The package structure and presence of design-pattern documentation indicate an architecture intentionally split along domain boundaries and reusable cross-cutting layers.
Main entry points: service/package-info.java Domain services · repository/package-info.java Repositories · controller/package-info.java Controllers · auth.service.ts Core layer
Components 22
Backend
Spring Boot REST API with layered domain services and JPA persistence.
- Backend app · Bootstraps the REST API and application context.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/SmartdeskBackendApplication.java - Security · JWT authentication, refresh tokens, revoked tokens, and access control.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/service/security/AuthService.java - Controllers · Role- and domain-specific HTTP endpoints.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/controller/package-info.java - Domain services · Core application logic for bookings, spaces, tickets, reviews, notifications, and admin workflows.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/service/package-info.java - Space domain · Spaces, rooms, desks, opening hours, amenity presets, and closures.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/model/space/Space.java - Booking domain · Bookings, statuses, waitlist entries, and availability rules.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/model/booking/Booking.java - Ticket domain · Tickets, severity, statuses, and note threads.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/model/ticket/Ticket.java - Review domain · Worker reviews and host-facing replies or notes.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/model/review/Review.java - Notifications · Stored notifications plus real-time broadcasting.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/service/notification/NotificationService.java - Admin ops · System logs, moderation, and administrative workflows.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/service/admin/SysAdminService.java - Repositories · Spring Data repositories over the relational database.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/repository/package-info.java - Mappers · Converts between entities and API payloads.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/mapper/package-info.java - DTOs · Request and response models used by the REST API.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/dto/auth/package-info.java - State machines · Explicit desk and ticket state transitions.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/service/desk/state/DeskStateMachine.java - Domain events · Booking-related events for waitlists and host cancellation notices.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/event/package-info.java - Policies & errors · Validation rules, business policies, and centralized REST error handling.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/exception/RestExceptionHandler.java - Seed data · Initial users, spaces, bookings, tickets, and reviews for dev mode.
smartdesk-backend/src/main/java/it/polimi/smartdesk_backend/config/bootstrap/DemoDataSeeder.java
Frontend
Angular SPA with role-based features and shared client integration.
- Frontend app · Bootstraps the Angular SPA and route configuration.
smartdesk-frontend/src/main.ts - Core layer · Shared API services, auth interceptors, guards, models, and utilities.
smartdesk-frontend/src/app/core/services/auth.service.ts - Role features · Role-based pages for auth, public, worker, host, technician, and admin.
smartdesk-frontend/src/app/features/worker/worker.routes.ts - Shared UI · Reusable shell, navigation, notification, and widget components.
smartdesk-frontend/src/app/shared/components/role-shell.component.ts - Environments · Runtime configuration for backend base URLs and build modes.
smartdesk-frontend/src/environments/environment.ts
Connections 24
- Backend app → Controllers: exposes · Creates the application context that serves the REST controllers.
- Controllers → Security: protected by · Endpoints depend on JWT authentication and role checks.
- Controllers → Domain services: delegates to · Controllers stay thin and forward requests to domain services.
- Domain services → Policies & errors: validates with · Business rules use shared policies and centralized exception handling.
- Domain services → State machines: enforces · Desk and ticket lifecycle transitions are managed explicitly.
- Domain services → Domain events: publishes · Booking flows emit observer-style domain events.
- Domain services → Repositories: persists via · Domain services read and write through JPA repositories.
- Domain services → Mappers: maps with · Services rely on mappers when returning DTOs.
- Mappers → DTOs: produces · Mappers construct the REST payload objects.
- DTOs → Controllers: transported by · Controllers accept requests and return DTO responses.
- Repositories → Space domain: stores · Persistence for space hierarchy and desk configuration.
- Repositories → Booking domain: stores · Persistence for bookings and waitlist entries.
- Repositories → Ticket domain: stores · Persistence for ticket lifecycle and notes.
- Repositories → Review domain: stores · Persistence for reviews and moderation data.
- Domain services → Notifications: updates · Service actions create notifications and broadcast events.
- Domain services → Admin ops: supports · Admin services coordinate logs and moderation workflows.
- Seed data → Repositories: loads into · Bootstrap data populates the underlying repositories.
- Frontend app → Environments: configures · The SPA reads runtime configuration for API routing.
- Frontend app → Role features: routes to · Root routing dispatches to role-based feature areas.
- Role features → Core layer: calls · Pages consume shared services, guards, and models.
- Role features → Shared UI: composes · Role pages are built from common shell and widgets.
- Core layer → Controllers: HTTP calls · Client services talk to the backend REST API.
- Core layer → Security: auth flow · JWT refresh and session handling align with backend security.
- Notifications → Core layer: pushes updates · Real-time notification stream is consumed by the SPA.