Document Management Platform
An architecture exercise: file storage, versioning, permissions and background processing, structured to stay maintainable.
The brief
What the finished thing needs to do.
- Upload documents with metadata, storing files outside the database
- Version documents, keeping previous versions retrievable
- Folder hierarchy with permissions that inherit
- Full-text search across document content
- Background processing for text extraction and thumbnails
- Audit log of every access and change
How to structure it
This is where clean architecture earns its cost. Business rules about permissions and versioning must be testable without a filesystem, a search index, or a message queue running.
Structure: a domain layer with the rules and no external dependencies; an application layer orchestrating use cases; an infrastructure layer implementing storage, search and messaging behind interfaces the inner layers define.
Background work goes through a queue because text extraction is slow and must not block an upload response. That introduces eventual consistency: a document is uploaded before it is searchable, and the interface has to represent that honestly.
Permission inheritance through a folder tree is the most subtle requirement. Resolve it deliberately rather than checking ad hoc at each call site.
Why these technologies
- Object storage for files, database for metadata
- Databases are poor at large binary data; object storage is built for it.
- Message queue for background work
- Keeps slow processing off the request path and allows retries.
- Interfaces defined by the domain
- Lets permission and versioning rules be tested with no infrastructure at all.
- Dedicated search index
- Full-text search over document content outgrows simple database queries.
Build it in this order
Each stage produces something that works. That matters — a project that only runs at the very end is a project people abandon.
Domain model
Documents, versions, folders and permissions as pure types with rules and no dependencies.
Test the rules
Permission resolution and version behaviour, tested with no infrastructure running.
Storage abstraction
An interface for file storage, with a local implementation first.
Upload and retrieve
Metadata to the database, file to storage, in a consistent way.
Versioning
New versions without losing previous ones; retrieve a specific version.
Permissions
Inheritance through the folder tree, enforced in one place.
Background processing
Queue text extraction. Handle failure and retry.
Search
Index extracted text and expose a search endpoint.
Audit log
Record access and change events without slowing the request path.
Done means
How to know it is finished
Check each of these before moving on. If one fails, the project is not done yet — and that is useful information rather than a setback.
- Domain rules are fully testable with no database, filesystem or queue
- Permissions inherit correctly and are enforced in one place, not per endpoint
- Uploading a document does not block on text extraction
- Previous versions remain retrievable after updates
- Failed background jobs are retried and surfaced rather than lost
- The audit log captures every access and change
If you want to go further
Extensions worth attempting
Only once the core build meets every criterion above.
- Add optical character recognition for scanned documents
- Add retention policies and automatic deletion
- Add document sharing via expiring links
- Add virus scanning in the upload pipeline
Other projects at this level
Analytics Dashboard
A data-heavy interface that stays fast and accessible: filters, charts, large tables and honest loading states.
AI Knowledge Assistant
The flagship AI project: a full assistant with retrieval, tool use, conversation, guardrails, evaluation and cost tracking.
Have a project worth talking through?
Tell us what you're building or what's slowing your current system down. We'll give you a direct read on scope and approach.