Record permission changes with durable audit evidence

Application background

An administrator changes a report from private to visible to the whole company. The next day its owner asks who made that change and when. The current permission setting answers who can see the report now, but it does not explain how that setting changed.

You need a separate history of permission changes. Each entry records the person, report, previous setting, new setting and time. This history is an audit trail. It must not quietly disappear when a later change replaces the current setting.

Example walkthrough

The permission change and its history entry belong in the same database transaction. Here, a transaction means that both changes are saved together or neither is saved.

Your assignment

Deliver: Build a permission-change operation that saves its history with the change. Add a view for investigating that history and a way to resume incomplete archive exports.

Required behavior: PATCH /reports/{id}/permissions saves the new permission version and its history record in one database transaction. GET /audit accepts a tenant-scoped resource ID and shows archive completeness separately from search freshness.

The required first milestone is a working local implementation of the behavior above. The numbered implementation steps define the scope. The cloud architecture is a later extension, not something the starter has already provisioned.

Get the code and run the supplied example

The code is in the public junior-to-staff repository. Install Git and Python 3.12+. No AWS account or Python packages are required for this first run. If you already have a checkout, use it and skip cloning.

git clone https://github.com/Soulful-Iris/junior-to-staff.git
cd junior-to-staff
python3 examples/architecture-starts/audit_trail.py

Supplied file: examples/architecture-starts/audit_trail.py. You can also read or download the source here (download file, source below).

"""Local mechanism demonstration for audit-trail. No AWS resources are created."""
import sqlite3,json
c=sqlite3.connect(':memory:')
c.executescript('CREATE TABLE permissions(id TEXT PRIMARY KEY,version INT,access TEXT); CREATE TABLE outbox(id TEXT PRIMARY KEY,payload TEXT);')
c.execute("INSERT INTO permissions VALUES ('report-7',1,'private')"); c.commit()
with c:
    c.execute("UPDATE permissions SET version=2,access='team' WHERE id='report-7' AND version=1")
    c.execute('INSERT INTO outbox VALUES (?,?)',('report-7:2',json.dumps({'actor':'ana','before':'private','after':'team'})))
print('After simulated crash before export:',c.execute('SELECT * FROM permissions').fetchall())
print('Still available to relay:',c.execute('SELECT * FROM outbox').fetchall())

This program is a mechanism demonstration: it runs the small scenario in one process and prints the result. It is not an HTTP service, a complete application, or an AWS deployment. A successful run demonstrates this mechanism only. It does not establish the workload or failure guarantees of the application you will build.

Example output from the supplied run:

Generated IDs and timestamps may differ. Compare the state transitions and outcomes.

After simulated crash before export: [('report-7', 2, 'team')]
Still available to relay: [('report-7:2', '{"actor": "ana", "before": "private", "after": "team"}')]

Set up your implementation workspace

Create work/audit-trail/ in your checkout (or use a separate repository). Copy the supplied mechanism into that directory as mechanism.py, then extract its state transitions into functions you can call from your implementation. The record and module names below describe what you must implement. They are not a promise that files with those names already exist. Keep a README.md beside your implementation with its exact run commands and observed results.

Local components and state to implement

This table names the records, interfaces or decision inputs for your deliverable. Unless a name is explicitly linked to supplied source above, it is something you create. Implement the local state transitions first, then connect the HTTP, storage or worker boundaries required by the steps.

Implement the assignment

1. Implement the permission transaction

Take actor and tenant from trusted authentication context. Require an expected resource version. In the same transaction, update the permission and append an event containing schema version, previous/new policy, request identity and server time. Do not turn an audit insertion failure into a successful unaudited change.

2. Export and reconcile evidence

Write a relay that reads committed outbox rows, uploads batches under immutable keys and records archive receipts. Retry with the same event IDs. Reconcile resource versions against archived events: an object checksum proves the bytes you have, not that every change reached the archive.

3. Build the investigator view

Query by tenant, report and time range. Show event sequence, actor and before/after state, plus archive watermark and search-index watermark. When the index lags, provide the retained object reference and an authorized Athena query path. Keep tokens and sensitive report content out of events.

4. Separate write privileges

The application may append archive objects but cannot overwrite evidence or shorten retention. Give investigation roles read-only access by scope. Record evidence access separately. Practice recreating the search projection from retained records.

Demonstrate the completed local result

Handoff: In your implementation README, include the start command, one successful operation, the failure case above and the resulting stored state or decision. State which dependencies are simulated. Someone with a fresh checkout should be able to reproduce this without your chat history.

Workload assumptions and capacity decisions

These are constructed exercise assumptions. The stated workload is a design target. The local demonstration does not establish that throughput. Use the estimation constants to check units before choosing capacity.

Map the local implementation to AWS

Deployment status: local only. Running the supplied command creates no AWS resources and configures no cloud connections. The diagram is a proposed deployment of the completed application. Each box needs either a deployed runtime, a provisioned service or an explicitly external dependency.

Read the diagram by following the arrows from the entry point: application code accepts the request or event, the state owner commits it, and any worker produces the later result. The table ties those roles to code and adapter work. Multiple boxes do not imply multiple Python files already exist.

Aurora establishes which change happened. S3 Object Lock protects the retained object versions after export. Athena reads the archive without making a mutable search index the sole evidence source.

Provision resources, then connect the application

Use one disposable AWS environment for the cloud exercise. Put the named resources in infra/template.yaml or your existing IaC tool, pass resource IDs through configuration, and scope each runtime role to its own tables, buckets and queues. The diagram is a design to implement. It is not a claim that these resources have been deployed. Record the commands you used to deploy and remove the exercise resources.

For concrete provisioning commands, configuration wiring and cleanup, use the AWS foundation guide. It includes a deployable table/queue/object-storage foundation and explains which application and service adapters you still implement.

A provisioned queue or table does not make the local program use it. Configure resource IDs in the deployed runtime, replace the local adapter, and replay the same successful and failing operation against that runtime. Record the deployed commit and observable result, then remove the disposable resources using your infrastructure tool.

Extend the design after the baseline works

Worked follow-up: Restore the application without rewriting audit history

The restored permission row says version 7, but the archive contains versions 8 and 9. Resuming writes as version 8 could give two different changes the same historical identity.

Revised architecture. Follow the changed responsibility and failure path below. This is a design to implement. The supplied local example does not provision these components.

What to implement. Keep mutation admission closed during recovery. Compare the restored checkpoint with retained audit sequences and recover resource state from an authoritative change log or a later verified backup. An audit event may be only evidence, not sufficient data to replay the business mutation. Record those gaps instead of guessing. Give the restored deployment a new recovery epoch, preserve original event IDs and rebuild the search projection separately. On AWS, restore RDS or DynamoDB into a fresh target and use S3 retained evidence without editing the archive.

Walk through the result. Use resource R at restored v7 with archived v8 granting access and v9 revoking it. Demonstrate that the first post-recovery read does not expose the v8 grant. Resume mutations only after proving v9 state or explicitly quarantining R. Supply a recovery ledger listing recovered and unresolved resources.

Design recovery when the database is restored to yesterday but the archive contains today’s events. Identify the latest proven resource version before permitting new changes. An append-only bucket cannot repair an application that reuses old event identities.