Home

1. Home (Home.md)

# SmartQuery**Transform your CSV data into insights with natural language queries.**
Welcome to the SmartQuery project! This wiki provides comprehensive documentation for developers, contributors, and users.
---## What is SmartQuery?
SmartQuery is a modern, full-stack application that lets users:
- Upload CSV files and manage data projects
- Ask questions in plain English and get instant answers
- Visualize data with charts and tables
- Use semantic search and advanced analytics
- Track query performance and monitor insights
---## Quick Links-[Architecture Overview](./Architecture)-[Frontend Guide](./Frontend)-[Backend Guide](./Backend)-[API Reference](./API-Reference)-[Testing & CI/CD](./Testing-and-CI-CD)-[Security & Compliance](./Security-and-Compliance)-[Deployment](./Deployment)

---

2. Architecture (Architecture.md)

# Architecture Overview
SmartQuery is a full-stack application with the following components:
-**Frontend:** Next.js 14 (TypeScript), Tailwind CSS, Zustand, Recharts
-**Backend:** FastAPI (Python), PostgreSQL, Redis, MinIO, Celery
-**Infrastructure:** Docker, Docker Compose, GitHub Actions CI/CD
## Key Features- Google OAuth authentication
- JWT token management
- Project and file management
- Natural language query interface
- Data visualization and analytics
- Async CSV processing and schema analysis
- Vector search (planned)
- SOC2-compliant security practices
## Directory Structure

SmartQuery/ backend/ frontend/ database/ docs/ infra/ shared/ scripts/

---

3. Frontend (Frontend.md)

# Frontend Guide## Tech Stack- Next.js 14 (TypeScript)
- Tailwind CSS + DaisyUI
- Zustand (state management)
- Recharts (charts)
- Axios (API requests)
## Features- Google OAuth login
- JWT token management
- Protected routes (dashboard, projects)
- File upload UI (CSV)
- Chat interface for queries
- Data visualization (charts/tables)
- Responsive, mobile-first design
## File Structure

frontend/src/ app/ components/ lib/ hooks/ styles/ tests/

## Development
- Run `npm install` in `frontend/`
- Start dev server: `npm run dev`
- Run tests: `npm run test`

---

4. Backend (Backend.md)

# Backend Guide## Tech Stack- FastAPI (Python)
- PostgreSQL
- Redis
- MinIO (S3-compatible)
- Celery (async tasks)
- Docker
## Features- Google OAuth authentication
- JWT access/refresh tokens
- User and project management
- File upload and storage (MinIO)
- Async CSV processing (Celery, pandas)
- Schema analysis and data insights
- Modular API with routers and services
## Development- Run `pip install -r requirements.txt` in `backend/`- Start dev server: `uvicorn backend.main:app --reload`- Run tests: `pytest`

---

5. API Reference (API-Reference.md)

# API Reference
See [docs/API_SPEC.md](../docs/API_SPEC.md) for the full OpenAPI-style documentation.
## Main Endpoints-`/auth/google` - Google OAuth login
-`/auth/me` - Get current user
-`/projects` - CRUD for projects
-`/projects/{id}/upload-url` - Get presigned upload URL
-`/projects/{id}/process` - Trigger CSV processing
-`/chat/{project_id}/message` - Send a query
-`/chat/{project_id}/messages` - Get chat history
-`/health` - Health check
## Error Codes
See the API spec for details.

---

6. Testing & CI/CD (Testing-and-CI-CD.md)

# Testing & CI/CD## Frontend- Unit/component tests: Vitest + React Testing Library
- E2E tests: Playwright
## Backend- Unit/integration tests: pytest
- Test database: SQLite
## CI/CD- GitHub Actions for lint, test, build, and security scan
- Node 18.x and 20.x supported
- ESLint v8 for Next.js 14 compatibility
## How to Run Tests- Frontend: `npm run test`- Backend: `pytest`

---

7. Security & Compliance (Security-and-Compliance.md)

# Security & Compliance## SOC2 Compliance
SmartQuery is designed with security and privacy in mind. The application will be **SOC2 compliant** to ensure the highest standards for handling sensitive user data.
- Secure authentication (Google OAuth, JWT)
- Encrypted storage (MinIO, PostgreSQL)
- Role-based access control
- Audit logging (planned)
- Regular security reviews and CI/CD checks
## Best Practices- All secrets managed via environment variables
- HTTPS enforced in production
- Regular dependency updates and vulnerability scans

---

8. Deployment (Deployment.md)

# Deployment## Local Development- Use `docker-compose.yml` to spin up all services (Postgres, Redis, MinIO, Celery, Flower)
- Frontend and backend can be run independently
## Production- Deploy frontend to Vercel, Railway, or static hosting
- Deploy backend with Docker (GKE, Railway, Fly.io, etc.)
- Environment variable validation on startup
## Environment Variables
See `.env.example` and `docs/ENVIRONMENT_SETUP.md` for required variables.