04 - Information Architecture (Webhooks Module)

1. IA map
2. Information entities
3. Cross-references
4. Navigation rules

Screens, routes, data entities and cross-references. The module owns two documents: webhooks (subscriptions) and webhook_delivery_logs (attempts). Read alongside 00-shared/05 (global IA).

1. IA map

Settings / Developer tools (web-first admin)
└── Webhooks                     (/webhooks)                  S1
    ├── Create webhook           (/webhooks/new)              S2
    ├── Webhook detail           (/webhooks/:id)              S3
    │   ├── Edit                 (/webhooks/:id/edit)         S4
    │   ├── Delivery logs        (/webhooks/:id/logs)         S5
    │   │   └── Log detail       (bottom sheet)               S6
    │   ├── Test delivery        (dialog)                     S7
    │   └── Retry delivery       (dialog)                     S8
    └── Pause / Resume           (inline action)              S9

All routes are client-side; the API is flat at /api/v1/webhooks* (webhooks.controller.ts:16-17).

2. Information entities

2.1 Webhook (`webhooks` collection, `webhook.schema.ts:8-30`)

Field	Type	Source
`name`	string, required	`webhook.schema.ts:10-11`
`url`	string, required (HTTPS expected)	`webhook.schema.ts:13-14`
`events`	`string[]`, default `[]`	`webhook.schema.ts:16-17`
`secret`	string, required	`webhook.schema.ts:19-20`
`enabled`	boolean, default `true`	`webhook.schema.ts:22-23`
`lastTriggeredAt`	Date (unused - never written)	`webhook.schema.ts:25-26`
`failureCount`	number, default 0 (unused - never written)	`webhook.schema.ts:28-29`
`tenantId`, `isDeleted`, `version`, `createdAt`, `updatedAt`	inherited	`base.schema.ts:10-34`

2.2 WebhookDeliveryLog (`webhook_delivery_logs` collection, `webhook-delivery-log.schema.ts:7-39`)

Field	Type	Source
`webhookId`	ObjectId ref `Webhook`	`webhook-delivery-log.schema.ts:9-10`
`eventType`	string, required	`:12-13`
`payload`	object (raw event payload)	`:15-16`
`status`	enum `pending / success / failed`, default `pending`	`:18-23`
`responseCode`	number	`:25-26`
`responseBody`	string	`:28-29`
`attemptCount`	number, default 0 (never incremented)	`:31-32`
`attemptedAt`	Date, default now	`:34-35`
`completedAt`	Date	`:37-38`

2.3 Domain events (the `events` picker vocabulary)

Event types are free-form strings on the wire (create-webhook.dto.ts:20-24); the client-side picker vocabulary is the set of emitted events. Representative registry: event-queue-map.ts:6-43 - UserRegistered, UserLoggedIn, PasswordResetRequested, UserCreated/Updated/Deleted, OrganizationCreated, AttendanceMarked/Updated, HomeworkCreated/Updated/Submitted/Graded/Deleted, ExamResultsPublished, StudentCreated/Updated/Deleted, TeacherCreated/Updated/Deleted, StaffCreated/Updated/Deleted, ParentCreated/Updated/Deleted, FeeStructureCreated, InvoiceIssued, PaymentCompleted. Plus the synthetic test event WebhookTested (webhooks.service.ts:134).

Event envelope (what the receiver gets): { eventType, tenantId, actorId, occurredAt, correlationId, payload } (domain-event.interface.ts:1-8).

3. Cross-references

Entity	Referenced by	Ref
Webhook	`WebhookDeliveryLog.webhookId`	`webhook-delivery-log.schema.ts:9-10`
EventBus (any event)	`WebhooksService.onAny`	`webhooks.service.ts:26-28`
`webhook-deliver` queue	`WebhooksModule` + worker	`queue.constants.ts:14`, `webhooks.module.ts:22`, `webhook-delivery.worker.ts:9`
Event names	`eventQueueMap`	`event-queue-map.ts:6-43`

S3 is the hub: metrics tile, recent logs preview, actions (edit, test, pause/resume).
S5 is reachable from S3 and from any "failed" badge deep link.
Pause/resume and test/retry never require leaving the current screen (dialogs).
Permission gating: webhook.create (S2), webhook.update (S4, S7, S8, S9), webhook.read (S1, S3, S5, S6) - permissions.constants.ts:89-92.
(planned) future: inbound public receiver under public scope (IMPLEMENTATION_PLAN.md:48); not in this IA.

Keyboard shortcuts

StudyLyon — Design Docs