Turn scattered files into a searchable knowledge base β then ask questions and get answers grounded in your own information.
Your important information is spread across PDFs, notes, reports, and documents. Finding one specific answer can mean opening files, searching manually, and piecing together details yourself.
BrainBox AI turns that process into a conversation.
Upload documents to your personal workspace, ask questions in natural language, and let a Retrieval-Augmented Generation (RAG) pipeline find relevant passages before an LLM generates a contextual response.
Less searching through files. More time using what you know.
If these preview images are not present in your local clone, add screenshots at
docs/images/landing-page.pnganddocs/images/login-page.png, or update the paths above.
| Capability | What it means |
|---|---|
| π Personal document library | Upload and manage documents in one knowledge workspace. |
| π¬ Ask questions naturally | Query your uploaded information using a conversational interface. |
| π§ Context-aware answers | Retrieve relevant document content and use it as context for AI-generated responses. |
| π Semantic retrieval | Use text embeddings and similarity-oriented retrieval to find relevant passages. |
| π Authentication | Register and log in with JWT-based authentication. |
| π€ User-scoped data | Associate documents and conversations with their respective users. |
| ποΈ Conversation management | Keep track of previous conversations. |
| βοΈ Separated AI service | Keep AI processing in a dedicated Python/FastAPI service, separate from the Express backend. |
BrainBox AI uses a modular, three-part application architecture:
- React + Vite client β provides the user interface for authentication, document uploads, and conversations.
- Express API server β handles application routes, authentication, user-related operations, and communication with the AI service.
- FastAPI AI service β processes document content, creates chunks and embeddings, retrieves relevant context, and requests a response from Groq.
flowchart TD
A([User asks a question]) --> B[React client]
B --> C[Express API]
C --> D[FastAPI AI service]
D --> E[Process the question]
E --> F[Retrieve relevant document chunks]
F --> G[Build contextual prompt]
G --> H[Groq LLM]
H --> I[Generate answer]
I --> J[Return answer to FastAPI]
J --> K[Express API]
K --> L[Display answer in client]
flowchart TD
A([Document upload]) --> B[React client]
B --> C[Express API]
C --> D[FastAPI AI service]
D --> E[Extract document text]
E --> F[Split text into chunks]
F --> G[Generate embeddings]
G --> H[Prepare searchable representations]
H --> I[(Application data stored/managed by backend)]
The diagrams describe the documented application flow at a high level. Exact persistence and retrieval implementation details may evolve with the codebase.
| Layer | Technologies |
|---|---|
| Frontend | React, Vite, JavaScript, HTML5, CSS3 |
| Application backend | Node.js, Express.js, REST APIs |
| AI service | Python, FastAPI |
| Retrieval & language models | RAG, Sentence Transformers, text embeddings, Groq API |
| Database | MongoDB / MongoDB Atlas |
| Authentication | JSON Web Tokens (JWT) |
| Development & source control | Git, GitHub |
Brainbox-ai/
β
βββ ai-service/
β βββ app/
β β βββ main.py
β βββ requirements.txt
β
βββ client/
β βββ public/
β βββ src/
β β βββ assets/
β β βββ components/
β β βββ App.jsx
β β βββ App.css
β β βββ main.jsx
β βββ package.json
β βββ vite.config.js
β
βββ server/
β βββ src/
β β βββ middleware/
β β βββ routes/
β β βββ db.js
β β βββ index.js
β βββ package.json
β βββ package-lock.json
β
βββ docs/
β βββ images/
β
βββ .gitignore
Install the following before starting:
- Node.js
- Python
- MongoDB Atlas account or a compatible MongoDB instance
- Groq API key
- Git
git clone https://github.com/Utkarsh-Raj-Profile/Brainbox-ai.git
cd Brainbox-aicd ai-service
python -m venv .venvActivate the virtual environment:
Windows PowerShell
.venv\Scripts\Activate.ps1macOS / Linux
source .venv/bin/activateInstall Python dependencies:
pip install -r requirements.txtCreate the AI service environment file and add the configuration required by the application. Then start FastAPI using the entry point and command configured in the project.
Open a second terminal from the project root:
cd server
npm installCreate server/.env and configure the database, authentication, client, and AI-service settings required by the backend. Start the server using the script defined in server/package.json.
Open another terminal from the project root:
cd client
npm installCreate client/.env and set the API base URL using the environment variable expected by the frontend. Start Vite:
npm run devOpen the local URL printed by Vite.
For the complete application, run the AI service, Express backend, and Vite frontend in their respective terminals. Make sure the URLs and ports configured by each service point to the correct local services.
Configuration note: The exact start commands and environment-variable names should be confirmed against the current
package.jsonfiles and source code. They are intentionally not guessed here.
Create separate environment files for each service. The names below reflect the configuration convention documented for this project; verify each variable against the implementation before running.
server/.env
PORT=5000
MONGODB_URI=your_mongodb_connection_string
JWT_SECRET=replace_with_a_long_random_secret
CLIENT_URL=http://localhost:5173
AI_SERVICE_URL=http://localhost:8000ai-service/.env
GROQ_API_KEY=your_groq_api_key
GROQ_MODEL=your_groq_modelclient/.env
VITE_API_BASE_URL=http://localhost:5000/api- Never commit
.envfiles, API keys, JWT secrets, or database credentials. - Keep secrets on the server side; do not expose private credentials through frontend environment variables.
- Do not upload confidential documents unless you understand how and where the application processes and stores them.
- Use a strong, unique JWT secret outside local development.
- Review authorization checks whenever adding or changing document and conversation endpoints.
The Express backend is organized around these documented route modules:
| Module | Base path |
|---|---|
| Authentication | /api/auth |
| Documents | /api/documents |
| Questions | /api/questions |
| Conversations | /api/conversations |
The FastAPI service is responsible for AI-oriented work such as document ingestion, retrieval, and question answering.
This project brings together several practical full-stack and applied-AI patterns:
- Retrieval-Augmented Generation: retrieve supporting content before generating an answer.
- Embeddings: represent text numerically to support similarity-based retrieval.
- Document chunking: break long documents into smaller passages that can be retrieved as context.
- Service separation: isolate AI workloads behind a dedicated FastAPI service.
- RESTful communication: keep the client, application API, and AI service responsibilities distinct.
- Authentication and authorization: protect user-specific application resources.
- Persistence: use MongoDB for application data.
Potential next steps for the project:
- Add automated tests for frontend, backend, and AI-service workflows.
- Expand supported document formats and extraction quality.
- Improve retrieval quality, ranking, and chunking strategies.
- Add more transparent source references for generated answers.
- Add document-level processing status and error visibility.
- Improve observability, structured logging, and failure handling.
- Add CI/CD checks and deployment documentation.
- Evaluate performance and scalability under larger document collections.
Ideas, bug reports, and pull requests are welcome.
- Fork the repository.
- Create a focused branch:
git checkout -b feat/your-change. - Make and test your changes.
- Commit with a clear message.
- Open a pull request describing the change and its impact.
For substantial changes, consider opening an issue first to discuss the approach.
Computer Science Engineer Β· Full-Stack Developer Β· AI Enthusiast
Building practical software at the intersection of web engineering and applied AI.
β If BrainBox AI is useful to you, consider starring the repository.
Built with β€οΈ by Utkarsh Raj
BrainBox AI β Your knowledge. Your intelligence. One workspace.

