A useful way to think about architecture is as two independent dimensions:
This avoids mixing terms such as “logical”, “application”, “deployment”, and “runtime”, which answer different kinds of questions.
Contextual
WHY does this system exist?
↓
Conceptual
WHAT major capabilities are required?
↓
Logical
HOW should those capabilities work together?
↓
Physical
HOW is this concretely implemented?
Defines the business problem, actors, goals, scope and external environment.
For a modern property search system:
Property seeker
↓
Search experience
↓
Relevant property listings
Business goals:
- improve search relevance
- support natural-language queries
- support text and image search
- reduce zero-result searches
- increase engagement / enquiry conversion
Typical artefacts:
Avoid implementation detail.
Defines the major capabilities required to satisfy the contextual goals.
Query Input
↓
Query Understanding
↓
Candidate Retrieval
↓
Candidate Ranking
↓
Search Results
A richer property-search version:
Text / Image Query
↓
Query Understanding
↓
Constraint Handling
↓
Candidate Retrieval
↓
Fusion
↓
Ranking
↓
Result Presentation
At this level:
Candidate Retrieval is meaningful.OpenSearch is too specific.Ranking is meaningful.cross-encoder running on GPU is too specific.The conceptual architecture should remain relatively stable even if the technology stack changes.
Decomposes capabilities into responsibilities and interactions without binding them to products or deployment units.
┌────────────────────┐
│ Query Understanding│
└─────────┬──────────┘
│
┌─────────▼──────────┐
│ Constraint Manager │
└─────────┬──────────┘
│
┌─────────────┴─────────────┐
│ │
┌───────▼────────┐ ┌───────▼────────┐
│Lexical Retrieval│ │Vector Retrieval│
└───────┬────────┘ └───────┬────────┘
│ │
└─────────────┬─────────────┘
▼
Fusion
↓
Reranking
↓
Result Selection
Logical responsibilities might include:
The important property is that these are logical components, not necessarily separate services.
For example:
Logical:
Query Understanding
Constraint Handling
Retrieval Routing
All three might later be implemented inside one service.
Maps logical responsibilities onto specific implementation technologies and infrastructure.
Web / Mobile
↓
Search API
↓
QUAPI service on GKE
↓
Retrieval orchestrator
↙ ↘
OpenSearch Qdrant
BM25 index HNSW vectors
↘ ↙
RRF fusion
↓
GPU reranker service
↓
Search API response
Physical decisions include:
These can change substantially while the logical architecture remains unchanged.
The abstraction hierarchy tells you how detailed the architecture is.
Viewpoints tell you what aspect of the architecture you are looking at.
A search platform may have all of these views:
Business
Application
Data
Integration
Runtime
Deployment
Technology
Security
Observability
Each can be expressed at different abstraction levels.
Focus:
What software responsibilities exist and how are they organised?
Logical example:
Search API
Query Understanding
Retrieval Orchestrator
Fusion
Reranking
Physical example:
search-api
query-understanding-api
ranking-service
Useful for:
Focus:
What information exists, where does it come from, and how is it represented?
Conceptually:
Property
Listing
Location
Search Query
Image
Search Result
Logically:
Listing
├── structured attributes
├── description
├── text embeddings
└── image embeddings
Physically:
OpenSearch index
- listing text
- metadata
- BM25 fields
Vector index
- listing_embedding
- image_embedding
For hybrid search, this viewpoint is particularly important because the same property may exist in several retrieval representations.
Focus:
How do components communicate?
Example:
Browser
│ HTTPS
▼
Search API
│ gRPC
▼
Query Understanding
│
├── OpenSearch API
├── Vector DB API
└── Ranking API
Questions include:
Focus:
What actually happens when a request executes?
This is one of the most useful views for search systems.
"3 bedroom house near the beach under $2m"
↓
Query normalisation
↓
Query understanding
↓
location = coastal area
beds >= 3
price <= $2m
↓
Metadata pre-filter
↓
┌───────────┴───────────┐
↓ ↓
BM25 retrieval Vector retrieval
20 ms 25 ms
└───────────┬───────────┘
↓
RRF
↓
Reranker
↓
top 20 results
This reveals things static component diagrams do not:
For search pipelines, the runtime view is often more operationally useful than the component view.
Focus:
Where does the software run?
GCP
│
├── GKE
│ ├── search-api pods
│ ├── query-understanding pods
│ └── ranking pods
│
├── OpenSearch cluster
│
├── Vector DB cluster
│
└── GPU inference endpoint
Adds concerns such as:
Deployment architecture is therefore usually a physical viewpoint, rather than a separate abstraction level.
Focus:
What technologies and platforms are used?
For example:
API → FastAPI
Container → Docker
Orchestration → GKE
Lexical search → OpenSearch
Vector search → Qdrant
Reranking → PyTorch / vLLM
Events → Kafka
Observability → OpenTelemetry
This view is useful for platform and engineering decisions, but it should not replace the logical architecture.
Focus:
Where are trust boundaries and controls?
For the property-search pipeline:
Internet
↓
API gateway
↓
Authenticated internal services
↓
Private search infrastructure
It may show:
Focus:
How do we understand system behaviour?
For search:
Query
↓
trace_id
↓
Query Understanding
↓
Retrieval
↓
Fusion
↓
Ranking
Metrics may include:
This is particularly valuable for ML/search systems because quality and infrastructure behaviour need to be observed together.
The useful model is therefore a matrix rather than one hierarchy.
| Conceptual | Logical | Physical | |
|---|---|---|---|
| Application | Search capabilities | Query understanding, retrieval, ranking | Concrete services |
| Data | Listings, queries, images | Search documents, embeddings | OpenSearch/Qdrant schemas |
| Integration | Systems exchange search data | APIs/events | REST/gRPC/Kafka |
| Runtime | Query → results | detailed pipeline flow | actual calls, timings, retries |
| Deployment | usually minimal | logical execution boundaries | GKE, clusters, regions |
| Security | trust domains | auth responsibilities | IAM, network policies |
| Observability | quality/health goals | metrics and tracing model | OTel, dashboards, alerts |
You normally do not need every cell.
The point is that they are available when useful.
A practical architecture document might contain just five diagrams.
Property Seeker
↓
Search Platform
↓
Property Listings
Explains why and scope.
Query
↓
Understanding
↓
Retrieval
↓
Ranking
↓
Results
Explains major capabilities.
Query
↓
Query Understanding
↓
Constraint Handling
↓
┌────────────┼────────────┐
↓ ↓ ↓
Lexical Text Image
Retrieval Vector Vector
Search Search
└────────────┼────────────┘
↓
Fusion
↓
Reranking
↓
Results
Explains how the search algorithm works.
request
↓
parse query
↓
generate embedding
↓
parallel retrieval
├── lexical
├── text vector
└── image vector
↓
candidate union
↓
RRF
↓
rerank top 100
↓
return top 20
Explains how a request executes.
GKE
│
Search API pods
│
Retrieval Service
↙ ↘
OpenSearch Qdrant
│
GPU Reranker
Explains what actually runs where.
The most useful mental shortcut is:
Abstraction = how concrete?
Contextual → Conceptual → Logical → Physical
Viewpoint = what are we examining?
Application / Data / Runtime / Deployment /
Integration / Security / Observability / ...
For a modern search system, I would normally prioritise conceptual architecture, logical pipeline, runtime/data-flow, and physical deployment. Those four views tend to expose most of the important architectural decisions without producing unnecessary documentation.