Αρχιτεκτονική runtime
Η αρχιτεκτονική εκτέλεσης runtime συντονίζει τα εισερχόμενα HTTP αιτήματα σε τέσσερα επίπεδα Clean Architecture: το presentation edge, τους pipeline interceptors, τα μοντέλα CQRS application & DDD domain, και την έγκυρη multi-tenant persistence.
Διαδραστικός χάρτης αρχιτεκτονικής
Ενότητα με τίτλο «Διαδραστικός χάρτης αρχιτεκτονικής»Ο παρακάτω χάρτης οπτικοποιεί τον κύκλο ζωής εκτέλεσης μιας mutation εντολής CQRS στα τέσσερα επίπεδα runtime, εμφανίζοντας τη σειρά των behaviors, τη διάδοση του context, το versioning του aggregate και την αναγνώριση persistence.
Άνοιγμα διαδραστικού χάρτη σε πλήρη οθόνη →
Επίπεδα Runtime
Ενότητα με τίτλο «Επίπεδα Runtime»1. Presentation layer (API & ingress)
Ενότητα με τίτλο «1. Presentation layer (API & ingress)»TenantSchemaMiddleware: Επιλύει το αναγνωριστικό multi-tenant από τις κεφαλίδες του αιτήματος, το επικυρώνει έναντι των ρυθμίσεων persistence, και καθορίζει το search path του tenant (TenantSchemaContext) πριν τη διαχείριση της διαδρομής.AuthSessionGuard: Επικυρώνει τα cookies συνεδρίας (session cookies) και τα διαπιστευτήρια bearer μέσω τουRequestPrincipalResolver, συνδέοντας ταreq.sessionPrincipalκαι CASL ability attributes στο context του αιτήματος.UsersController: Επικυρώνει τα schemas των payloads με Zod (CreateUserDtoSchema), μεταφράζει την είσοδο σεCreateUserCommand, και την αποστέλλει μέσω του CQRS command bus.CommandBus: Αποστέλλει την εντολή στον pipeline runner που έχει συνδεθεί κατά το bootstrap της εφαρμογής.
2. Pipeline interceptor layer (cross-cutting onion)
Ενότητα με τίτλο «2. Pipeline interceptor layer (cross-cutting onion)»PipelineRunner: Συνδέεται κατά το bootstrap της εφαρμογής για να περικλείσει τις μεθόδους των handlers σε μια αλυσίδα delegates onion μέσα στοAsyncLocalStorage(pipelineStore). Αρχικοποιεί ταtenantIdκαιcorrelationIdστοPipelineContext.LoggingBehavior: Μετρά την καθυστέρηση εκτέλεσης, καταγράφει αιτήματα και αποκρίσεις, και αποκρύπτει ευαίσθητες ιδιότητες του payload χρησιμοποιώντας το@cqrs-ddd/safe-stringify.CaslBehavior: Επιβάλλει κανόνες εξουσιοδότησης επιπέδου τύπου (requires({ action, subject })) πριν εκτελεστεί η λογική του handler, αποτυγχάνοντας με fail-closed συμπεριφορά μέσω τουUnauthorizedActionException.IdempotencyBehavior: Δεσμεύει ένα operation token στο Redis πριν την εκτέλεση. Σε αναπαραγωγή (replay), συγκρίνει το αποθηκευμένοrequireAbilityDigestγια να διασφαλίσει ότι ο καλών δεν έχει χάσει τα δικαιώματά του.
3. Application & domain layer (CQRS & DDD core)
Ενότητα με τίτλο «3. Application & domain layer (CQRS & DDD core)»ICommandHandler&EventPublisher: Οι handlers υλοποιούν τοICommandHandler<C, R>του NestJS με τη μέθοδοexecute(). Τα domain events γίνονται commit μέσω τουEventPublisherτου NestJS (publisher.mergeObjectContext(aggregate).commit()) μετά από ανθεκτική αποθήκευση στο repository.CreateUserHandler: Ενορχηστρώνει τη δημιουργία του aggregate (User.create()), αξιολογεί το post-mutation CASL authorization πεδίων (authorizer.authorize()), αναθέτει την αποθήκευση στο command repository, και υποβάλλει (commits) τα domain events.Useraggregate root: Ενθυλακώνει τους επιχειρησιακούς κανόνες, εφαρμόζει τοUserCreatedEvent, και παρακολουθεί τη γραμμή βάσης της αναμενόμενης έκδοσης (version). Τα setters παραμένουν private για ενυδάτωση (hydration) από το ORM.
4. Persistence & infrastructure layer (έγκυρη βάση δεδομένων & ουρές)
Ενότητα με τίτλο «4. Persistence & infrastructure layer (έγκυρη βάση δεδομένων & ουρές)»@PersistedWrite: Επιβάλλει αυστηρή σειρά κύκλου ζωής γύρω από την αποθήκευση στο repository:@Cache(ακυρώνει δευτερεύοντα κλειδιά αναζήτησης) →@AcknowledgePersisted→@MapPersistenceErrors.CreateUserCommandRepository: Επαληθεύει το autocommit, αποθηκεύει το aggregate μέσω του tenant-scopedEntityManager, και καλεί τοuser.acknowledgePersisted()μόνο αφού η υποβολή (commit) στη βάση δεδομένων επιτύχει.UserCreatedHandler: Καταναλώνει τοUserCreatedEventυπό το@UsePipeline(deadLetter()), εισάγοντας στην ουρά το background job αποστολής email καλωσορίσματος.BullMQ Queue: Μεταφέρει ασύγχρονες εργασίες παρασκηνίου με υποστήριξη dead-letter στο Redis, διαδίδοντας τα metadata τουJobContext(tenant, correlation ID και principal) πέρα από τα όρια των jobs.