How sfuller14/semantic-consensus works
This project is best diagrammed as a single-app Streamlit frontend with AI/search integrations, not as a classic multi-service backend architecture.
What this project is
From the README and file tree, Commercial Consensus is a hackathon-built e-commerce semantic search and conversational recommendation app. It uses:
• Streamlit for the UI
• Pinecone for vector search
• OpenAI embeddings to encode product/review text
• Cohere rerank to refine search results
• OpenAI ChatCompletions for the chat experience
• Docker + AWS Elastic Beanstalk for deployment
The repo is small, which strongly suggests the application logic is concentrated in main.py and wrapped by Streamlit.
End User / Browser
• The person using the app.
• Initiates search, view, and chat actions.
Streamlit App (main.py)
• This is the core application layer.
• Since there is no separate backend directory, treat this as the UI + orchestration layer.
• Search UI
• Product Detail / View UI
• Chat UI
Query Orchestration / Business Logic
• Inside main.py or logically adjacent to it.
• Handles:
• user input parsing
• filter construction
• Pinecone queries
• reranking
• prompt assembly for chat
Pinecone Vector Index
• Stores embedded product/review vectors.
• Main retrieval layer for semantic search.
OpenAI Embeddings API
• Used during indexing or preprocessing to create text-embedding-ada-002 vectors.
Cohere Rerank API
• Used after Pinecone retrieval to reorder results.
• Important to show as a second step after initial vector search.
OpenAI ChatCompletions API
• Used in the chat workflow to generate natural-language answers from retrieved reviews/specs.
Product/Review Dataset / Indexed Corpus
• Even though the repo does not contain the ingestion scripts, the README makes clear that the system depends on:
• product specs
• customer reviews
• title/metadata fields
• This as an upstream data source that feeds the embedding/indexing pipeline.
Deployment Layer
• Docker
• AWS Elastic Beanstalk
Architectural patterns to highlight
This project uses several important design ideas:
a) Monolithic UI + orchestration
There is no separate backend service in the repo tree, so represent main.py as a single orchestration monolith rather than pretending there is a microservice architecture.
b) Retrieval-Augmented Generation style pipeline
The chat flow is essentially a RAG-like pipeline:
• retrieve relevant review/spec text
• rerank results
• feed into an LLM for response generation
c) Hybrid search
The README explicitly describes:
• tabular/metadata filtering
• semantic vector search
• reranking
That makes this a hybrid search system, not just a pure vector search app.
d) Offline indexing pipeline
Even though not present in the tree, the architecture depends on a preprocessing/indexing step:
• source data → embeddings → Pinecone index
Technologies to label
Be explicit with names, because the project relies heavily on external AI services.
Core stack
• Python
• Streamlit
• Pinecone
• OpenAI API
• embeddings
• chat completions
• Cohere API
• rerank
Deployment / ops
• Docker
• AWS Elastic Beanstalk
Supporting files
• requirements.txt → dependencies
• .streamlit/config.toml → Streamlit runtime/config
• docker/Dockerfile → container build
• docker/docker-compose.yaml → local composition/testing
• docker/Makefile → convenience build/run commands
Best-practice recommendation for this specific project
• detailed enough to show the AI retrieval chain,
• but honest that most logic lives in one Streamlit app.
Deployment via Docker on AWS
That will capture the real architecture much more accurately than splitting it into fake frontend/backend microservices.
> “main.py acts as both UI and orchestration layer; external AI services handle indexing, retrieval, reranking, and generation.”