Files
slp-modular-cms/aidlc-docs/features/contact-forms-module/inception/application-design/application-design.md
T
SluijsensandClaude Sonnet 5.5 bc763c8ef6 Aanbod: RESTful routes zonder /admin, één OfferingDto en herordenen via PUT /offerings/order
Admin en bezoeker gebruiken dezelfde resource; alleen GET is anoniem, de rest vereist AdminOnly. OfferingAdminDto vervalt (displayOrder zit nu in OfferingDto), move-up/move-down zijn vervangen door de order-route die een onbekende of onvolledige lijst met 400 afwijst. De admin-frontend en alle tests zijn mee aangepast.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-10 13:06:08 +01:00

6.9 KiB

Application Design (minimal) — contact-forms-module

Scope: component names, boundaries, configuration keys, and the few design points the contract leaves open. Behaviour and field-level detail stay in contract v0.3.1.

1. Repo findings that shape the design (master d9cc539)

  • Modules are IModule classes discovered via the host's project references (orchestrator.DiscoverModules()); a host gets a module by a ProjectReference in its .csproj. Phase 1 registers Contact in Api.SlpSoftware only; Api.AndreaSlopFotografie does not exist on master and gets the reference after the ASF merge (Phase 2).
  • Data Protection is already host-level: AddCmsDataProtection() (CmsHost) persists keys in the database (ApplicationDbContext) with a fixed application discriminator. Contact therefore does not own a key ring; it only asks IDataProtectionProvider for a protector with a per-site purpose string. (This replaces the plan wording "keyring in own DbContext".)
  • Controller convention: [Route("offerings")] under the global /api/v1 prefix, class-level [Authorize(Policy = "AdminOnly")], public actions [AllowAnonymous] + [EnableRateLimiting("<policy>")], admin actions under offerings/admin. Existing public limiter policy: offerings-public.
  • /System/capabilities lists ModuleOrchestrator.ModuleNames: a module named Contact appears automatically.
  • AvailabilityMiddleware is prefix-bypass based, with verified-admin-token bypass. Existing admin routes are not under a common /api/v1/admin/ prefix (they are .../admin suffixes or controllers such as Users).

2. Deviation to confirm (admin route shape)

Contract § 6 writes /api/v1/admin/contact-messages. Repo convention is contact-messages/admin... (as offerings/admin). Proposal: follow the repo convention: GET /api/v1/contact-messages/admin, GET .../admin/{id}, PATCH .../admin/{id}, DELETE .../admin/{id}, POST .../admin/{id}/resend. The 503-regression test then iterates over all endpoints without [PublicSiteEndpoint] instead of relying on a prefix. Redesign - SLS to update the contract (or veto).

3. Components

Component Project Responsibility
PublicSiteEndpointAttribute Core (Availability) marker, AttributeTargets.Method; read via endpoint metadata
Availability check Modules.Availability AvailabilityMiddleware minimal change: after the prefix bypass, context.GetEndpoint()?.Metadata.GetMetadata<PublicSiteEndpointAttribute>() != null => next (deny-by-default otherwise)
429 handling Core AddCmsRateLimiting OnRejected set Retry-After (from MetadataName.RetryAfter when available, else window), write application/problem+json; keep the security-event call
Offering category Modules.Offerings Offering.Category (nullable, max 100), DTOs/requests, ICategoryOptions (reads Offerings:Categories), validation in service
ContactModule Modules.Contact IModule "Contact"; registers DbContext (MySQL, same pattern), services, hosted services; Migrate() in UseModule
ContactDbContext Modules.Contact ContactMessages, IdempotencyRecords
ContactMessagesController Modules.Contact public token + submit ([PublicSiteEndpoint], [AllowAnonymous], limiter policies); admin actions AdminOnly (U4)
ContactSubmissionService Modules.Contact validate, classify (genuine/spam), idempotency, store, trigger mail
ContactValidator Modules.Contact pure function: input => {field: [codes]}; shared rules (trim, length, regex, control chars)
ContactTokenService Modules.Contact issue/verify via IDataProtector (purpose SlpModularCms.Contact.Token.{siteId}), ITimeProvider; verify result: valid / tooYoung / expired-or-invalid
ICaptchaVerifier (+NullCaptchaVerifier, later Friendly Captcha impl) Modules.Contact fail-open on provider failure, log without PII
IContactMailSender (+NoOpContactMailSender) Modules.Contact seam for mail; real implementation in Phase 2 (CMS-U5)
ContactRetentionService Modules.Contact daily BackgroundService: delete rows past retentionUntil and idempotency records > 24 h
ContactSiteOptions Modules.Contact Contact:* binding (validated on start; recipient/sender not required until mail is wired)
Log scrubbing Core Observability extra rule in SecurityEventProcessor/Sentry BeforeSend for the contact routes

4. Configuration keys

Key Default Notes
Offerings:Categories [] per host; empty list => category must be null
Contact:SiteId host name derived from host config, never from the request; used in the token purpose and stored on rows
Contact:MinSeconds 3
Contact:TokenLifetimeMinutes 120
Contact:RetentionMonths 12 per row at insert
Contact:SpamRetentionDays 30
Contact:MaxSpamRowsPerDay 200 cap per site per day, then 202 without storing
Contact:MaxBodyBytes 16384
Contact:HoneypotField hpCheck
Contact:RecipientEmail, Contact:SenderEmail none env-only for ASF; not committed (Phase 2)
Contact:Captcha:Enabled/Provider/SiteKey/Secret false secret via env/secrets
RateLimiting:ContactForm 5 / 600 s per client IP
RateLimiting:ContactToken 20 / 600 s per client IP
RateLimiting:ContactResend 5 / 600 s admin resend

5. Data

  • ContactMessage: Id (Guid), SiteId, ReceivedAt, Name, Email, Subject, Message, Status (New|Read|Archived|Spam|Converted), MailStatus (Pending|Sent|Failed|NotApplicable), MailError (code only), MailAttempts, NextMailAttemptAt, RetentionUntil. Indexes: (SiteId, Status, ReceivedAt), RetentionUntil. No IP.
  • IdempotencyRecord: Key (Guid), SiteId, CreatedAt, StatusCode; unique index (SiteId, Key). No request content.
  • Offering.Category: varchar(100) NULL.

6. OpenAPI export

  • Committed file openapi/cms-api.v1.json in the repo root. A test builds the document from the SlpSoftware host (AddOpenApi) and compares it to the file; set UPDATE_OPENAPI=1 to rewrite it. Drift fails the build, so cms-client always generates from a current file.
  • The contract's response components (Validation, TooLarge, RateLimited, Problem) are declared through an IOpenApiDocumentTransformer so the exported shape matches contract § 8.

7. Cross-cutting decisions

  • Identical 202 for genuine and spam: same code path up to the store step; spam differs only by Status=Spam and RetentionUntil=+30d, and never triggers mail.
  • Invalid/forged/other-site/expired token => errors.token = ["expired"]; too-young token => silent spam path.
  • Logging: only status code, site id and outcome enum for these routes; request logging for them is disabled; a test asserts that a thrown exception's log entry holds no body or field value.
  • Security Baseline is checked at each stage (anonymous endpoint, input limits, no oracle, secrets only via env, generic 5xx, headers).