A full-stack application template with a Python (Litestar) backend and a TypeScript (Next.js) frontend, connected via GraphQL and REST, plus an optional SwiftUI iOS client. Ideal for hackathons and rapid prototyping, designed to smoothly evolve from a PoC into an MVP.
- Nova 🌟
- Python – Core programming language for backend.
- Litestar – High-performance ASGI framework for modern Python web apps.
- Advanced Alchemy – SQLAlchemy integration (async) + migrations tooling.
- GraphQL – API query language for flexible data fetching.
- REST – Resource-oriented APIs over HTTP with JSON.
- PostgreSQL – Advanced open-source relational database known for reliability.
- Redis – In-memory data store for message brokering.
- Celery – Distributed task queue for handling asynchronous background jobs.
- Flower – Real-time monitoring for Celery workers.
- uv – Ultra-fast Python package and project manager.
- ruff – Extremely fast Python linter and code formatter.
- ty – Fast, type-safe Python type checker.
- TypeScript – Core programming language for frontend.
- Next.js – React framework for production-ready applications.
- Tailwind CSS – Utility-first CSS framework for rapid UI development.
- pnpm – Fast, disk space efficient package manager.
- Storybook – Tool for building UI components and pages in isolation.
- Vitest – Next generation testing framework.
- Playwright – Reliable end-to-end testing for modern web apps.
- Biome – Fast formatter and linter for JavaScript/TypeScript projects.
- Docker Desktop – Provides Docker Engine and Docker Compose.
- mise – Manages tool versions.
- Task – Task runner designed for modern workflows.
- pre-commit – Manages and runs automated Git hooks.
- Swift – Primary language for the iOS client.
- SwiftUI – UI framework for modern iOS interfaces.
- Xcode – IDE and simulator for iOS development.
- Docker Desktop
- Xcode (for iOS development)
Run the setup script to install dependencies and configure the environment:
./setup.shNote: if you get permission denied, run
chmod +x setup.shthen retry./setup.sh.
After it finishes, start services in separate terminals:
task backend:dev
task worker:dev
task beat:dev
task frontend:devOptionally, monitoring:
task flower:dev-
Verify Docker is available:
docker --version docker compose version docker info
-
Install mise:
curl https://mise.run | shIf this fails, see the official install docs.
-
Install the project toolchain:
mise install -y
-
Install pre-commit hooks:
pre-commit install
-
Copy the example environment files:
cp .env.example .env cp backend/.env.example backend/.env cp frontend/.env.local.example frontend/.env.local
-
Pull database image:
task infra:pull
-
Start database service:
task db:up
-
Install backend dependencies:
task backend:install
-
Install frontend dependencies:
task frontend:install
-
Start backend:
task backend:dev
-
Create an initial admin user:
task backend:create-admin-user
-
Generate frontend code based on the backend API:
task frontend:codegen
-
Start frontend:
task frontend:dev
-
Start background worker:
task worker:dev
-
Start periodic task scheduler:
task beat:dev
-
Start monitoring (optional):
task flower:up
The services will be available at:
This project is pre-configured for VS Code (or any fork like Cursor or Windsurf) to provide a seamless development experience:
- Type Checking: Since we use
ty, the"python.languageServer"setting is set to"None"in.vscode/settings.json. This avoids running two language servers simultaneously when the Python extension is enabled (see official ty configuration).
An iOS starter app lives in the ios directory.
- Open ios/ios.xcodeproj in Xcode.
- Select a simulator or device.
- Run the app from Xcode.
Key entry points:
This project uses a canonical rule system to manage AI/LLM coding rules, first oriented to VS Code + GitHub Copilot (and compatible agents like Cursor or Antigravity).
- Always-on standards live in
.github/instructions/. - Task-specific workflows live in
.github/skills/. - Prompt files (workflow entry points) live in
.github/prompts/.
- Canonical rules are defined in
.github/instructions/. AGENTS.mdprovides a cross-agent routing layer that delegates to those canonical files.backend/AGENTS.mdprovides backend-local scoping while still delegating to the canonical instruction files.frontend/AGENTS.mdprovides frontend-local scoping while still delegating to the canonical instruction files.ios/AGENTS.mdprovides iOS-local scoping while still delegating to the canonical instruction files.
This is an opinionated deployment recommendation that has worked well in production, but you are free to deploy this template using any providers or infrastructure that fit your needs.
This template has been deployed successfully with the frontend on Vercel and the backend + database on Render.
See full deployment details in docs/deployment.md.
This project uses Task to simplify common development workflows. The main
Taskfile.yml in the project root provides commands for:
- Managing the Docker environment (for example, building, starting, or stopping services).
- Running development tasks within the
backendandfrontendservices (such as linting, formatting, or testing). - Managing background workers (Celery worker and beat).
- Inspecting worktree-specific infrastructure settings with
task infra:env. - Running full-stack validation with
task validate.
To list all available tasks, run:
task --listThis project uses GitHub Actions for continuous integration and validation:
- PR Validation: Enforce PR title conventions and limit PR size.
- CI Workflow: Run tests and linting on both frontend and backend.
For detailed information about our CI/CD workflows, see the workflows documentation.
All versioned changes are documented on the GitHub Releases page.
This project is licensed under the MIT License.