Architecture
Overview of the HyperSaaS tech stack and project structure.
Tech Stack
Backend
| Technology | Purpose |
|---|---|
| Django 5 | Web framework |
| Django REST Framework | API layer |
| PostgreSQL + pgvector | Database with vector search |
| Celery + Redis | Background tasks |
| Stripe | Plans, checkout and billing portal |
| Docker | Containerization |
Frontend
| Technology | Purpose |
|---|---|
| Next.js 16 | React framework |
| TypeScript | Type safety |
| Tailwind CSS v4 | Styling |
| shadcn/ui on Base UI | Component library |
| NextAuth | Authentication |
AI Agent System
HyperSaaS uses a pluggable multi-framework agent architecture:
- LangGraph — Default handler, with tool calling and streamed replies
- PydanticAI — Alternative handler for structured outputs
- Custom — Extend
BaseAgentHandlerfor any framework
Project Structure
backend/
├── backend/
│ ├── chat/ # Chat sessions, messages, AI handlers, streaming
│ ├── core/ # Rate limits, tracing
│ ├── documents/ # Knowledge base, RAG, embeddings, evaluation
│ ├── users/ # Accounts
│ ├── workspaces/ # Multi-tenancy, AI usage metering
│ └── subscriptions/ # Plans and Stripe billing
├── config/ # Django settings, URLs, API router
├── docs/ # Plans, evaluation reports and runbooks
└── requirements/ # Pip dependencies
frontend/
├── src/
│ ├── app/ # Next.js App Router pages
│ ├── components/ # UI components
│ ├── lib/ # Utilities, types, actions
│ └── config/ # Site configuration
└── public/ # Static assets