{"slug": "portfolio-website-architecture-for-dummies", "title": "Portfolio Website Architecture for Dummies", "summary": "Adam Belton, the developer behind AdamBelton.com, has detailed the architecture of his portfolio website, which uses a ports-and-adapters pattern to support his upcoming AI-powered product, ThoughtForm. ThoughtForm is a conversational thinking workspace that helps users explore and articulate their thoughts through an AI assistant, building an inspectable idea map. The website's architecture is designed to simplify complexity, with a shopping centre metaphor illustrating how different project units share resources like storage and AI services.", "body_md": "This website serves two purposes:\n\nSoon, I'll be releasing my first demo product: [ThoughtForm](https://adambelton.com/products/thoughtform).\n\nThoughtForm is a conversational thinking workspace where an AI assistant helps you explore, organise and articulate what you think or feel. Through focused questions, examples, clarification, challenge and alternative perspectives, it helps you develop an evolving idea map you can inspect and correct. If it would be useful, it can then bring that understanding together into a coherent expression, in your own words. It is useful when something is bothering you, but you cannot quite put your finger on why.\n\nIt's not quite ready to show you yet, though.\n\nIn the meantime, I thought I'd tell you how this website works under the hood. Its architecture.\n\nBut instead of just talking about its architecture, I'm going to talk about how I think about its architecture. Architecture is inherently technical, and what interests me about building things is simplifying complexity.\n\nTechnically, the website uses a version of something called ports-and-adapters architecture. It has a host, delivery and application layers, capabilities, ports, adapters and composition.\n\nI designed the architecture around those ideas. The technical language is useful because it gives each part a precise name. But knowing the names of things isn't the same as having a mental model for how they fit together.\n\nI understand technical concepts best when I can see the underlying model with my eyes closed. It's a tool I use whenever something has lots of moving parts: I turn it into a picture I can hold in my head, move around and explain without relying on the technical language.\n\nThis is the picture I use for the website's architecture.\n\nHere we go.\n\nImagine AdamBelton.com is a shopping centre. I'm Adam, and I own it.\n\nThere is a big unit at the front where I display my writing. Down a corridor are some smaller units where my projects operate. One of those projects is ThoughtForm, but we'll get to that later.\n\nThese projects could have their own buildings in different locations. But I like having them here, so you can visit them in one place instead of driving all over town.\n\nOne benefit of having them here is that they can share the shopping centre's resources. These include:\n\nRight now, you're inside the shopping centre. You're in the main unit, looking at my writing. You haven't passed security because you haven't needed to. The writing is open to everyone.\n\nIf you were visiting one of the private project units, you would have to pass security first. They would ask you to sign in and check whether you were allowed through.\n\nThen you get to ThoughtForm.\n\nThe way ThoughtForm works is that you have a conversation. You talk about what you're thinking or feeling, and the assistant asks questions to help you explore it. While that's happening, ThoughtForm builds an idea map: an inspectable view of the ideas you establish and the perspectives you explore. If you decide it would be useful, ThoughtForm can help you bring those ideas together in your own words.\n\nWe'll get into more detail about how this works and why it exists another time, but for now, let's get back to the shopping centre.\n\nYou walk into ThoughtForm, and here's the layout.\n\nThere is a receptionist at the front. Somewhere behind the receptionist, there is a floor manager wandering around. Behind the floor manager are three departmental offices with signs on their doors: conversations, idea maps and drafting. Inside each office is a specialist for that department.\n\nAt the back are two more doors marked storage and AI. We can't see behind them, but they connect the project unit to restricted areas of the shopping centre.\n\nWhen ThoughtForm's unit was being designed, it told the shopping centre's fit-out team that it would need storage and AI.\n\nBut here is the important bit: ThoughtForm doesn't know how the shopping centre provides either of them. It doesn't deal with the suppliers or know what the restricted areas look like. It just knows what it needs to be able to ask for at each door.\n\nThis matters because ThoughtForm might want to relocate one day. It can't take the shopping centre's storage rooms or AI suppliers with it. But it can take the design of its doors. A new building would only need to connect suitable services on the other side.\n\nBefore the unit opened, the shopping centre's fit-out team connected those doors to the services it had chosen. If the shopping centre upgrades a service or changes suppliers, it can change what is behind the door without ThoughtForm needing to redesign itself.\n\nBack to ThoughtForm. And you.\n\nWhen you start a conversation, you speak to the receptionist. She passes your message to the floor manager.\n\nThe floor manager makes two copies. One goes to the conversations department. The other goes to the idea map department.\n\nThe conversation specialist takes your message through the AI door. A response starts coming back, and it makes its way through the floor manager and receptionist to you.\n\nAt the same time, the idea map specialist takes their copy through the AI door. They are not trying to respond to you. They are looking for ideas you have established, corrected or developed. If they find something useful, the idea map is updated.\n\nThe work that needs to be kept is passed through the storage door.\n\nThere are two important points here.\n\nThe first is that the conversations department and the idea map department work independently. They receive the same message, but they do different jobs and finish in their own time. The floor manager doesn't make you wait for the idea map before the conversation can continue.\n\nThe second is that this happens over and over again. You send a message, the floor manager coordinates the work, and each department handles its own area of expertise using services supplied by the shopping centre.\n\nIf you later decide to bring your thinking together, the drafting department gets involved. It works with the material you have established and helps create a draft in your own words. The draft is optional. You can use ThoughtForm to explore something without ever producing one.\n\nThat's the picture.\n\nLike any metaphor, it isn't a perfect representation. It keeps the relationships I need to see and leaves out the details I don't.\n\nNow the technical language has somewhere to live.\n\nThe shopping centre is the **host**. It provides the shared environment and infrastructure.\n\nPreparing the unit and connecting everything before it opens is **composition**.\n\nThe routes and roads that bring you to the right place are **HTTP**. ThoughtForm's entrance and receptionist are its **delivery** layer. In another architecture, I might have called this a controller.\n\nThe floor manager is the **application** layer. She coordinates the complete job without doing the specialist work herself.\n\nThe departments are **capabilities**. They own the rules for conversations, idea maps and drafting. The specialists inside them are **services**.\n\nThe storage and AI doors are **ports**. ThoughtForm designs them around what it needs, without knowing what is behind them.\n\nThe connections fitted to the other side are **adapters**. They translate between ThoughtForm's needs and the shopping centre's actual services.\n\nIn shorthand:\n\n```\nDelivery receives.\nApplication coordinates.\nCapabilities decide.\nPorts describe what is needed.\nAdapters connect the product to real services.\nComposition connects everything.\n```\n\nThat is not the only way to describe this architecture. It might not even be the metaphor that works for you. But it is the one that lets me see the whole thing at once.\n\nAnd that matters to me.\n\nI don't think understanding something means being able to repeat its terminology. I think it means being able to turn it around in your head, look at it from another angle and explain it without relying on the original language.\n\nThe code already shows what I've built. The repository is open for anyone who wants the technical detail. What I want to show here is how I make sense of it.\n\nWhen a system becomes complicated, my instinct is to look for the smallest picture that preserves the important relationships. In this case, it was a shopping centre: a host, a fitted-out unit, a receptionist, a floor manager, some specialist departments and a couple of carefully designed doors.\n\nThat is how I see the architecture with my eyes closed.\n\nIf you ever understand the individual words in a technical explanation but still find the whole thing difficult to hold in your head, try looking for the picture underneath them. It doesn't have to be a shopping centre, and it doesn't have to make sense to anyone else at first.\n\nFind the mental model that lets you see how the parts relate. Then give the technical language somewhere to live.", "url": "https://wpnews.pro/news/portfolio-website-architecture-for-dummies", "canonical_source": "https://dev.to/oldmanbelton/portfolio-website-architecture-for-dummies-46i2", "published_at": "2026-08-15 08:11:27+00:00", "updated_at": "2026-08-15 08:40:41.279431+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-products", "developer-tools"], "entities": ["Adam Belton", "AdamBelton.com", "ThoughtForm"], "alternates": {"html": "https://wpnews.pro/news/portfolio-website-architecture-for-dummies", "markdown": "https://wpnews.pro/news/portfolio-website-architecture-for-dummies.md", "text": "https://wpnews.pro/news/portfolio-website-architecture-for-dummies.txt", "jsonld": "https://wpnews.pro/news/portfolio-website-architecture-for-dummies.jsonld"}}