Personal data in a generated project
Summary. A generated project knows which of its columns hold personal data, and erases a person
from all of them with one command. init writes the privacy folder of the platform (--privacy on,
the default with an ORM): the lists of the copies and of the exports each context declares, and the
scripts privacy:erase and privacy:export. generate repository <context> <Aggregate> --personal <column>,... declares what a table keeps of a person, next to its mapper, and writes once per
context the erasure and the export that read every such declaration: two ports, their adapters over
the ones of the ORM package, their fakes, one spec and their lines in the copies and the exports of
the platform. With --event-sourcing on, the key of the person in the event store is destroyed first, so that their stored events read
as erased. These are the mechanisms of privacy by design, built in by default; what a tool cannot
decide, the lawful basis of a processing or the completeness of a declaration, stays the project's
own, and this page says so. The pieces of the kit this page rests on:
Event sourcing for the sealing of stored events,
Audit trail for the dated proof,
Multitenancy for what a tenant confines.
What a generated project holds
Section titled “What a generated project holds”| Written by | What | Where |
|---|---|---|
init --privacy on (on with an ORM, off without one or when asked) |
the lists of the copies and of the exports the contexts declare, the list of the events that carry personal data (personal-events.ts, written by docs), runErasure, runExport and runPurge, the nightly job privacy.purge-expired, the three scripts |
src/platform/privacy/, scripts/privacy-erase.ts, scripts/privacy-export.ts, scripts/privacy-purge.ts |
init --event-sourcing on (off unless asked) |
the event store, the keys of the data subjects and the cipher that seals a personal value of a stored event, audited when the trail is on | src/platform/event-sourcing/, the event_store schema |
generate repository <ctx> <Aggregate> --personal <column>,... |
the columns in the storage, their declaration, and once per context the erasure and the export that read it | the context |
generate personal-fields <ctx> <table> --personal <column>,... --subject <column> |
the declaration of a table no aggregate owns, joined to the erasure and the export of the context, or written with them | the context |
A project without personal data takes --privacy off and pays nothing; a project whose aggregates
are all rows keeps --event-sourcing off and pays no table for it. Both are recorded in the config
(stack.privacy, stack.eventSourcing) and changed later by init --force
(CONFIG.md).
Declaring what a table keeps of a person
Section titled “Declaring what a table keeps of a person”npx ddd-ts-kit generate repository billing Customer --personal email,display_namenpx ddd-ts-kit generate repository billing Invoice --personal customer_email --subject customer_id --erasure rowThe first command declares that the customers table keeps the email and the display name of the
person the row is about, named by its id: an erasure pseudonymises them, the row stays and each
reads [erased]. The second declares that the invoices table copies the email of a customer, named
by customer_id, and that an erasure deletes those rows. Each command:
- adds the columns to the table and to the row type of the aggregate, as nullable text; the mapper
writes them empty, with a note, until the aggregate carries them (a value object
Email, a field of the state); - writes the declaration
infrastructure/persistence/<aggregate>.personal-fields.tsnext to the mapper, withpersonalFieldsof the kernel, spelled as the erasure of the ORM reads it: the SQL names on Knex and Prisma, the properties of the definition on Drizzle and TypeORM; - the first time in a context, writes its erasure: the port
application/ports/<context>-personal-data-erasure.port.ts, an abstract class that extendsPersonalDataErasureof the kernel; the adapterinfrastructure/persistence/<orm>-<context>-personal-data-erasure.repository.ts, which extends the erasure of the ORM package (KnexPersonalDataErasure,DrizzlePersonalDataErasure,PrismaPersonalDataErasure,TypeOrmPersonalDataErasure) with the declarations of the context, confined to the tenant of the work when the repository is tenant-scoped; its fake; a spec that saves two people through the repository, writes their personal columns and proves the erasure and the export on the test database; and its binding, the@Repositorydecorator in the declared style, the module file of an explicit context, the factory of a hand-wired platform; - the first time in a context too, writes its export: the port
application/ports/<context>-personal-data-export.port.ts, which extendsPersonalDataExportof the kernel; the adapterinfrastructure/persistence/<orm>-<context>-personal-data-export.repository.ts, which extends the export of the ORM package (KnexPersonalDataExport,DrizzlePersonalDataExport,PrismaPersonalDataExport,TypeOrmPersonalDataExport) with the same declarations, confined to the tenant the same way; its fake; bound the same way; - lists the two ports once, in
src/platform/privacy/data-subject-copies.tsanddata-subject-exports.ts, between the markers;init --forcelists them again when it rewrites the files; - a later table of the same context joins the
declarationsof both adapters, between markers.
// infrastructure/persistence/customer.personal-fields.ts, as generated on Knexconst TABLE = { schema: BILLING_SCHEMA, table: 'customers' };
const declaration: PersonalFieldsOptions<CustomerRow> = { subject: 'id', fields: ['email', 'display_name'], erasure: 'pseudonymise',};
export const CustomerPersonalFields = personalFields(TABLE, declaration);The subject column names the data subject a row is about, an opaque identifier: id when the row
is the person, the column that holds the id of the person otherwise. It is never personal data
itself, and the generator refuses a subject listed in --personal. The columns are given by their
SQL names, lower case letters, digits and underscores; a column the generated table keeps for itself
(id, version, tenant_id, the audit columns, the registered_at of a table generated before 0.100) is refused, as is a project
without the privacy folder (init --force --privacy on) or without an ORM package that ships the
erasure (--orm none, --orm custom).
The two modes, settled per table:
--erasure |
What the rows of the person read afterwards | When |
|---|---|---|
pseudonymise (the default) |
the row stays, each personal text column reads [erased], any other personal column reads nothing (it has to accept null) |
a row others point to, a fact of the business that names the person by an opaque id |
row |
the rows of the person are deleted | a pure copy of the person, a contact, an address book entry |
A table no aggregate owns
Section titled “A table no aggregate owns”A read model, a table of received messages, a table written by hand in the schema of the context:
each may keep a copy of a person, and none has an aggregate generate repository could name.
npx ddd-ts-kit generate personal-fields billing payment_reminders --personal customer_email,customer_name --subject customer_idThe table is given by its SQL name and has to exist in the schema file of the context:
<context>.schema.ts on Drizzle and TypeORM, create-<context>-tables.schema.ts on Knex,
prisma/schema/<context>.prisma on Prisma. The command:
- writes
infrastructure/persistence/<table>.personal-fields.ts(payment-reminders.personal-fields.ts, which exportsPaymentRemindersPersonalFields), spelled as the erasure of the ORM reads it: on Drizzle and TypeORM with the properties the definition of the table gives its columns, read in the schema file, on Knex and Prisma with the SQL names; - joins it to the
declarationsof the erasure and of the export of the context when they exist; - otherwise writes them as the first table of a context does (ports, adapters, fakes, binding, the
lines in the copies and the exports of the platform). The spec differs: no repository nor builder
writes the rows of such a table, so
test/integration/<context>-personal-data.spec.tsproves the fakes and names each case to prove on the test database asit.todo(erased for the subject and left to the others, exported, purged with--retention), for you to write with rows inserted as the project writes that table.
It never changes the table. A column --personal, --subject or --retention names that the
definition does not hold is refused, with the columns it has; when the definition takes columns
from elsewhere (a spread, a helper called on the table), the command cannot tell, declares the
column and says in its output to check that the table holds it. Where the erasure is confined to a
tenant (--tenant-scoped, or a project whose stack.tenancy is not none), the table has to hold
tenant_id too.
--subject is required here. On a table without aggregate the row is rarely the person, and a
default of id would have npm run privacy:erase -- <person> look for the person in the wrong
column while the register says the table is covered. Give --subject id only when the id of the
row is the id of the person.
Refused: a table the schema of the context does not declare (the command lists the ones it does),
a table that has a declaration already (add the column to its fields by hand), and whatever
--personal of a repository refuses. generate repository <ctx> <Aggregate> --personal ... run on
an aggregate whose table exists is refused too, since the generator declares a table once: add the
columns to the table by hand, then declare them with generate personal-fields.
The erasure, end to end
Section titled “The erasure, end to end”npm run privacy:erase -- <subject-id> [--operator <who-asks>] [--rerun] runs on the sources with the
variables of .env. The script opens the persistence, composes the application, opens an execution
context of origin cli with the operator as actor, and runs eraseDataSubject of the kernel over:
- the key of the subject, when the project has an event store: destroyed, so that every stored
event of the person reads
[erased]at the next replay, and audited when the trail is on; - every copy listed in
data-subject-copies.ts, one port per context, resolved from the application: each adapter erases or pseudonymises the rows of its declared tables, in the tenant of the work; with--tenancy shared-table, the tenant directory names the tenants (the organisations of the identity context when the project has it, elseTENANTS, comma separated) and a copy runs once per tenant, since a write of tenant data is never widened; with--audit on, each copy leaves an entrypersonal-data:erasewith the operator and the number of rows,0included, with or without an event store; - what the platform keeps of the person in tables no tenant confines, once: in every record of the
outbox that names the person, pending, published or dead, the fields the
personaloption of its event lists (platform.outbox, frompersonal-events.ts), and every job enqueued with the person assubject, whatever its status (platform.background-jobs): a waiting job never runs, a running one stops at its next heartbeat. Each leaves its entry too; - the projections fed by the store, rebuilt once the key is gone: given by hand for now, where the
runner says
TODO(platform).
It prints the report as JSON: whether a key was destroyed, the rows each context and the platform
reached, the projections rebuilt. A copy or a rebuild that fails does not stop the others, and the
first failure is thrown once everything ran: running the erasure again completes one that failed half way. An
erasure that reached nothing is refused, exit code 1, and announced to nobody: the id is mistyped,
its tenant is missing from the directory, or the person was erased already, and the entries of the
audit trail say which. --rerun says it is expected: the exit code is 0 and the erasure is announced
again. A subject that is not an opaque identifier (a name, an email) is refused before anything is
touched.
Once every copy is erased, runErasure publishes privacy.data-subject.erased through the outbox
(dataSubjectErasedV1 of the kernel, { subjectId, erasedAt }: the id of the person and nobody else, the operator staying in the audit trail that its correlation id leads to),
once per tenant with shared tables; the relay of the running application delivers it. An erasure
that failed publishes nothing, and running it again does, with --rerun when nothing is left to
reach. This is how article 19 reaches beyond the database the platform holds:
- a context extracted into a service of its own erases its copy on its side:
npx ddd-ts-kit generate erasure-handler <context>writes the idempotent handler of the event over the erasure of the context, its spec on the fake and its subscription (the decorator, the module file, or the hand-wired platform, in a transaction behind a broker). In the monolith the platform has erased that copy already, and the handler reaches nothing: an erasure is idempotent. A context whose aggregates are event-sourced has no table and needs no such handler: its personal values are sealed bypersonalData(subjectId, value)and the key destroyed in step 1 erases them in every context at once, sogenerate erasure-handlerrefuses it and says so. A projection that keeps a clear copy is rebuilt once the key is gone, and an erasure on a date of the business (a retention of five years after the relationship ended) is a scheduled job of your own that calls the same key destruction (Event sourcing); - a system outside the project that consumes the events of the project, and copied the person from one of them, subscribes to the same type: the event catalog and AsyncAPI list it;
- an integration event that carries personal data says so (
personal: { subject, fields }ondefineIntegrationEvent): the catalog writes it under the payload, AsyncAPI asx-personal-data, so that every consumer knows which copy it keeps (@ddd-ts-kit/events).
In a handler spec, the fake of the erasure (Fake<Context>PersonalDataErasure) counts the rows it
holds of a person and forgets them at the first erasure, like the fake of a repository.
The export, end to end
Section titled “The export, end to end”npm run privacy:export -- <subject-id> [--operator <who-asks>] > export.json answers the right of
access and to portability (GDPR articles 15 and 20) the same way: the script composes the
application, opens an execution context of origin cli with the operator as actor, and runs
exportDataSubject of the kernel over every export listed in data-subject-exports.ts, one port
per context, in every tenant the tenant directory lists with shared tables (the organisations of the identity context, else TENANTS), since a read of tenant data is
confined to its tenant as a write is. Each adapter reads the same declarations as the erasure and
answers one record per row about the person, under <context>.<table>, with the personal columns
and the keys of the files as plain data, no other column and nothing of anyone else; a row
pseudonymised already reads [erased], a row deleted answers nothing. With --event-sourcing on,
runExport also hands over what the event store keeps of the person, through
EventStorePersonalDataExport of the kernel: one record per event that holds a value sealed with
the key of the person, under platform.event-store.<event type>, naming its event (stream,
aggregateId, version, occurredAt), each value opened and named by its path in the data of the
event (reason, contacts[0]). A stream is named after its aggregate, not after the person, so
this export reads the whole store, in rounds of 500 events in the order of their positions, in each
tenant; the store commits its appends in that order, so a round never misses an event. A value
whose key an erasure destroyed is gone and answers nothing; a value that does not decipher is named
in unreadable, and the export goes on. The result is one document:
{ "format": "ddd-ts-kit/personal-data-export@1", "subject": "cus_42", "exportedAt": "2026-10-24T09:30:00.000Z", "records": [ { "source": "billing.customers", "values": { "email": "ada@example.org", "display_name": "Ada" } }, { "source": "billing.invoices", "values": { "customer_email": "ada@example.org" } }, { "source": "crm.contacts", "values": { "email": "ada@example.org", "phone": null } }, { "source": "platform.event-store.care.dossier.opened", "values": { "note": "Asthma" }, "event": { "stream": "care.dossier-d1", "aggregateId": "d1", "version": 1, "occurredAt": "2026-10-02T08:15:00.000Z" } } ]}Structured, commonly used and machine-readable, as article 20 asks; dated, so that what it states is true of that instant; named by the format, so that a reader knows the shape and a later shape is told apart; naming the person by the opaque id alone. Hand it over to the person, then delete the file. The exports run in the order listed, so a document reads the same from one run to the next, and one that fails stops the gathering: a document that silently lacked a context would state less than the system keeps. A subject that is not an opaque identifier is refused before anything is read: an export looks a person up by id, never by a name or an email, which would be a search in personal data.
With --audit on, runExport wraps every port with auditedPersonalDataExport of
@ddd-ts-kit/audit: one entry per context, category data-access, action personal-data:export,
the operator, the subject, the context and the number of records, never the values, written before
the records are handed over, so that no document leaves without its trace. This is the
accountability of article 5(2) for the right of access: who read what of whom, and when
(Audit trail). The trail is
append-only, so every run is a handover and leaves its entry, a trial included: try the script on a
test subject, never on a real person.
In a handler spec, the fake of the export (Fake<Context>PersonalDataExport) hands over the records
a test gave it and remembers who was asked.
Retention, every night
Section titled “Retention, every night”npx ddd-ts-kit generate repository billing Customer --personal email,display_name --retention ended_at:36m--retention <column>:<n><d|m|y> says how long the rows keep the person (GDPR article 5(1)(e)),
counted from the end of the relation with the person: a column of yours that dates it, ended_at
above, which joins the storage as a nullable timestamp, empty while the relation lasts; a row whose
date is empty never expires. The declaration gains retention: { after: 'ended_at', months: 36 },
and the generated spec proves the purge on the test database. Fill that column when the relation
ends (the contract closed, the account deleted), in the mapper of the aggregate that knows it.
Never count a retention from the beginning: created_at (or the registered_at of an older table) dates the creation of the row, and a purge
counted from it would erase, every night and for good, people who are still customers. The
generator refuses it, as it refuses the other columns the table keeps for itself, a personal column,
the subject and a period that is not one positive unit; a declaration written by hand takes the
same care.
Every night at 03:00 UTC, the job privacy.purge-expired of the platform runs runPurge: every copy
listed in data-subject-copies.ts erases, as its declaration says, the rows that outlived their
retention, in every tenant, since the work of a job names none and a tenant left out of a list would
keep what it should not, the one write of the kit across tenants
(Multitenancy); with --audit on, each copy leaves an entry personal-data:purge with the
number of rows, 0 included, and no person. JOB_PRIVACY_PURGE_EXPIRED_ENABLED=false switches the
job off in one environment, and npm run privacy:purge runs it by hand and prints the rows reached
per context. A table whose declaration gives no retention keeps its rows until the person asks.
The platform keeps traces of its own work, and they are purged the same way. At 03:30 UTC,
events.purge-published drops the records of the outbox published more than OUTBOX_RETENTION_DAYS
ago; at 03:45 UTC, jobs.purge-finished drops the jobs that succeeded or were cancelled more than
BACKGROUND_JOBS_RETENTION_DAYS ago, thirty days each by default. A record and a job row keep their
payload until then. A dead event or a dead job stays until an operator decides, and an erasure
reaches it all the same. JOB_EVENTS_PURGE_PUBLISHED_ENABLED=false and
JOB_JOBS_PURGE_FINISHED_ENABLED=false switch one off in one environment.
A project that reads its periods from configuration (an environment variable such as
RETENTION_PERIODS, a JSON object from copy to period) and purges by its own job declares no
literal retention, which the register would write as until erased: it names the configuration
instead, configuredRetention: 'RETENTION_PERIODS', and the register says
configured by `RETENTION_PERIODS` . The kit reads the key from the text of the source and never
the value, and its own purge runs only from a literal retention; the two are refused together.
The period itself stays the project's to state, in the controller section of the register.
How long is the project's decision, not the tool's: the duration a law imposes (accounting, health), or the one the purpose needs. Write it in the register with its reason.
The register, generated
Section titled “The register, generated”npx ddd-ts-kit docs reads every declaration and every integration event, and writes what the
system keeps of people in two places, which docs --check holds to the code like the rest:
- the Personal data section of each
CONTEXT.md: one row per table (the column that names the person, the personal columns and files, what an erasure does, how long the rows are kept), then the events whosepersonaloption says their payload carries some; docs/privacy/register.md, with--privacy on: the same rows across the contexts, the columns named as the database names them whatever the ORM, and each event that carries personal data with the contexts downstream of its producer.
| Context | Table | About | Personal data | On erasure | Kept ||---|---|---|---|---|---|| billing | `customers` | `id` | `email`, `display_name` | pseudonymised | 36 months after `ended_at` |The register is the inventory a project maintains, not the record of processing activities of
GDPR article 30: that record also names the purposes, the lawful basis, the recipients outside the
system and the transfers, which no code says. The file leaves them to the controller, in sections
outside the markers that docs never rewrites, with what the code does not purge (backups, logs,
files, the archives of the audit trail). A table is in the register only if a declaration names it.
The rules
Section titled “The rules”Five rules of ddd-ts-kit check hold a project whose stack.privacy is on to its declarations,
as warnings, and they stay warnings: they read names, never contents, and a column address may
name a warehouse. A team that wants one blocking sets its severity to error in rules of the
config. A project that chose off hears nothing from them.
| Rule | Reports |
|---|---|
privacy/declared-field |
a column named like personal data (email, phone, birth_date, address, iban... the vocabulary of the kit, with privacy.vocabulary of the config added and privacy.allow removed) that no declaration of its context names, on the four ORMs |
privacy/event-payload-declared |
a field of the payload of an integration event named like personal data that its personal option does not list |
privacy/erasure-reaches-copies |
a context that consumes an event carrying personal data and erases nothing when the person is erased |
privacy/subject-is-opaque |
a subject that is personal data itself (an email as the key of a person) |
privacy/no-personal-data-in-logs |
a call to the logger or the metrics that names a declared personal field |
privacy/snapshot-sealed |
a value of a snapshot mapper named like personal data that no personalData seals |
They read names, not contents, which is why each one says what it cannot see
(npx ddd-ts-kit explain privacy/declared-field). A column that holds nothing of a person in a
project (the shared mailbox of a team) is a deviation recorded where it is written,
// ddd-ts-kit-disable-next-line privacy/declared-field -- ADR-NNNN: <why>, or a word of
privacy.allow. An event stream has no table: a key of an event mapper that the same file seals
with personalData(subject, value) is declared by that, and only a key stored in clear is reported.
What stays out of reach
Section titled “What stays out of reach”- Backups and the retention of the broker. An erasure reaches the database, never a backup nor a
message already published: the bound of an erasure is a date, which the retention policy decides.
The announcement reaches the consumers that are running and subscribed; a message already in a
dead letter queue or on a topic stays there until its retention ends. A record of the outbox is in
the database: the erasure reaches it, and only by the fields the
personaloption of its event lists, throughpersonal-events.ts, whichddd-ts-kit docskeeps. A record still pending goes out with[erased]in place of the field: a consumer whose schema refuses that text refuses the event, and nothing of the person leaves. - A field no
personaloption lists, a job that names nosubject. The payload of an event is read by its declaration, and a job row is found by itssubject:privacy/event-payload-declaredreports a field named like personal data, and nothing reports a job that holds a person in its payload without naming them. A job about a person is enqueued with{ subject: personId }. Jobs kept in the memory of a process (--queue memory) are out of reach of a script that runs in another one, and end with that process. The keys of the event store make the events of a backup unreadable once destroyed, which is why they live apart, with a shorter retention (Event sourcing). - What a cache keeps. An erasure does not reach the
Cacheport: a value acachedread keeps of a person stays there until its time to live, once the row is gone. A read that answers a person takes attlMsthe retention of the project accepts, or is not cached. - Logs and exports already handed over. Nothing of the kit rewrites them; the log adapters mask credentials, not names (Observability).
- A column no declaration names. A rule reads the name of a column, not what a text field may
contain: a
notescolumn may hold a diagnosis. The declarations are the inventory a project maintains, andprivacy/declared-fieldreports only a column whose name holds a word of the vocabulary (see The rules). - A read model. A projection keeps its rows in a read model store, not in a table of its own:
it declares nothing yet. The rebuild of a projection fed by the event store removes the clear copy
it kept, once given to
rebuilds. A read model in OpenSearch is reached as Search read models says. - The columns the aggregate does not write yet. The mapper writes the declared columns empty until the aggregate carries them; the erasure of an empty column reaches the row all the same.
What the tool does not decide
Section titled “What the tool does not decide”The kit provides the technical measures of privacy by design (GDPR article 25): declaration, erasure, export, a dated proof, a retention purged every night and a generated register. The lawful basis of each processing, the information of the data subjects, the processors and the impact assessment are the project's own; whether a pseudonymised row is an erasure in the eyes of the law is for the controller to decide, as the audit trail page says of what stays in the chain. The document of an export carries the data; the information that goes with an answer to a request of access (the purposes, the recipients, the retention, the rights of the person, article 15(1)) is the letter the project writes around it. By construction means built in by default, never a legal guarantee.
See also
Section titled “See also”- Event sourcing, per aggregate: the sealing of stored events and the keys
- Audit trail: the dated proof of an erasure and of an export, the masks keyed by data subject
- Multitenancy: what a tenant confines, and why an erasure runs once per tenant
- File storage: the files of a person, declared as
filesof a declaration - Privacy by design, beyond event sourcing: the parts built and the parts to come, the wording to use
- The CLI reference:
init(--privacy,--event-sourcing) andgenerate repository(--personal,--subject,--erasure),generate personal-fieldsfor a table no aggregate owns