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.