How yousif-gh/guidely works
Guidely lets employees ask questions about company documents and receive grounded answers with cited sources. The main workflow runs from the search page through the FastAPI ask route, vector retrieval and score filtering, then Groq answer generation; the UI displays the answer and sources. A separate admin workflow uploads or reindexes text documents, which are parsed, chunked, embedded and indexed. Health and in-memory metrics provide operational visibility. The README documents frontend/backend operation; the specific frontend-to-API wiring is not shown in the excerpts, so that link is marked unverified.
Main entry points: vector_store.py Vector indexing and retrieval · search.py Search and ask routes · main.py FastAPI app · documents.py Document routes
Components 18
User interface
- Page navigation
frontend/src/App.jsx - Ask and sources
frontend/src/pages/SearchPage.jsx - Source display
frontend/src/components/SourceList.jsx - Document admin
frontend/src/pages/AdminPage.jsx
API and workflows
- FastAPI app
backend/main.py - Search request
backend/models/record.py - Document routes
backend/routes/documents.py - Search and ask routes
backend/routes/search.py
Document indexing
- Text documents
backend/data/sample-docs - Text parsing and chunks
backend/services/parsing.py - Local embeddings
backend/services/embeddings.py
Retrieval and answers
- Vector indexing and retrieval
backend/services/vector_store.py - Answer generation
backend/services/llm.py
State and metrics
- FAISS index and chunks
- Embedding cache
- Request and cache metrics
backend/services/metrics.py
Other components
- Employee
- Groq API
Connections 25
- Employee → Page navigation: uses
frontend/src/App.jsx - Page navigation → Ask and sources: renders
frontend/src/App.jsx - Page navigation → Document admin: renders
frontend/src/App.jsx - Ask and sources → Search and ask routes: submits question
- Ask and sources → Source display: renders sources
frontend/src/pages/SearchPage.jsx - Document admin → Document routes: manages documents
- FastAPI app → Document routes: registers
backend/main.py - FastAPI app → Search and ask routes: registers
backend/main.py - FastAPI app → Request and cache metrics: records requests
backend/main.py - FastAPI app → Request and cache metrics: reads snapshot
backend/main.py - FastAPI app → Vector indexing and retrieval: reads index state
backend/main.py - Search and ask routes → Search request: validates requests
backend/routes/search.py - Document routes → Text documents: writes and lists
backend/routes/documents.py - Document routes → Text parsing and chunks: validates upload
backend/routes/documents.py - Document routes → Vector indexing and retrieval: builds index
backend/routes/documents.py - Vector indexing and retrieval → Text documents: reads documents
backend/services/vector_store.py - Vector indexing and retrieval → Text parsing and chunks: chunks text
backend/services/vector_store.py - Vector indexing and retrieval → Local embeddings: embeds chunks
backend/services/vector_store.py - Vector indexing and retrieval → FAISS index and chunks: writes and searches
backend/services/vector_store.py - Local embeddings → Embedding cache: reads and writes
backend/services/embeddings.py - Local embeddings → Request and cache metrics: records cache
backend/services/embeddings.py - Search and ask routes → Vector indexing and retrieval: retrieves chunks
backend/routes/search.py - Search and ask routes → Answer generation: generates answer
backend/routes/search.py - Answer generation → Groq API: requests completion
backend/services/llm.py - Search and ask routes → Request and cache metrics: logs model errors
backend/routes/search.py