PuglieseWeb Engineering Handbook
Why this handbook exists
Section titled “Why this handbook exists”PuglieseWeb builds AI products — Ema Answers, SystemDox — and consults on the architecture behind them. Twenty years of designing payment networks and cloud platforms, and lately AI-assisted delivery, kept returning the same questions. How should a service be shaped? What does a secure default look like on AWS? How does a team keep its systems evolving without losing control of them? And how do you make an organisation’s technical knowledge usable by everyone in it, rather than only by the person who happens to hold it?
This handbook is where those answers are written down once. It is the reference behind our engagements: the material a client gets instead of a slide deck, and the shared vocabulary a piece of work starts from. Publishing it openly is deliberate — a practice that can be read is a practice that can be checked.
What it covers
Section titled “What it covers”| Section | What you will find |
|---|---|
| AWS | Compute, storage, databases, networking, security, monitoring, messaging, migration, automation, and governance and cost. |
| Software Design | Microservices, hexagonal architecture, event-driven systems, distributed-systems fundamentals, API gateways and transaction models. |
| Security and Cloud Data Security Principles | Secure coding, encryption and key management, identity, separation of duties, tokenisation and data classification. |
| Guides, Technologies, Dev Tools, DMS | Writing a service, observability, HTTP and networking fundamentals, Kafka, Kubernetes, Unix, Vault, and Oracle-to-PostgreSQL migration. |
Use the search box for a specific term; it searches the full text of every page.
Who it is for
Section titled “Who it is for”- Engineers and technical leaders evaluating or working with PuglieseWeb, who want to see how we think before they see a proposal.
- Teams who want a practitioner’s reference rather than vendor marketing: the trade-offs, not only the happy path.
How this differs from the blog
Section titled “How this differs from the blog”The blog is where PuglieseWeb argues a position: an article with an author and a point of view, which ages on purpose. The handbook is where the reference lives — structured, versioned in git, and revised in place rather than reposted. When a blog post rests on a concept, it links to the handbook page that defines it. Read the blog to learn what we think; read the handbook to learn how something works.
Each product’s documentation lives with the product. The company’s own decision records and platform architecture are kept on an internal site and are not published here.
How current it is
Section titled “How current it is”Every page prints, at its foot, the date and revision of the change that last touched it, and the revision the site was built from. Nothing about freshness is written into a page by hand, so nothing about it can quietly go out of date: the footer is read from git when the site is built.
One caveat, worth stating plainly rather than letting a reader infer it. This library was imported into a new repository in August 2026 and did not bring its previous history with it, so a page that has not been revised since the import carries the import’s date rather than the date it was written — some of that material is several years old. Pages revised since are dated honestly. Where cloud services are concerned, treat a vendor’s own current documentation as the authority over anything here.
If a page is wrong, tell us. Corrections go in as pull requests, and a merge rebuilds the site within minutes.