Nova Stack 🌟

A modern full-stack application template built for quick and efficient project setup.

📚 Table of Contents

• Tech Stack
• Getting Started
• Development Tasks
• Troubleshooting
• CI/CD Workflows
• Releases
• License

🛠️ Tech Stack

Backend

• Python – Core programming language for backend.
• Litestar – High-performance ASGI framework for modern Python web apps.
• Piccolo – Async ORM and query builder with migration support.
• PostgreSQL – Advanced open-source relational database known for reliability.
• GraphQL – API query language providing a more efficient alternative to REST.

Frontend

• TypeScript – Core language for frontend, adding static types to JavaScript.
• Next.js – React framework for production-ready applications.
• Tailwind CSS – Utility-first CSS framework for rapid UI development.
• Chart.js – Simple yet flexible JavaScript charting library.

🚀 Getting Started

Prerequisites

The primary prerequisites for this project are:

• Docker Desktop: Provides Docker Engine and Docker Compose.
• Task: A task runner / build tool used for managing common development workflows.
• pre-commit: A tool for managing and running pre-commit hooks.

Alternative Installation

Alternatively, install the components separately:

• Docker Engine: Version 28 or later.
• Docker Compose: Version 2 (V2) or later.

Verifying Installation

Verify the installation by running:

docker --version
docker compose version
task --version
pre-commit --version

Environment Setup

1. Copy the example environment files:

   cp .env.example .env
   cp backend/.env.example backend/.env
   cp frontend/.env.local.example frontend/.env.local
   

2. Edit the environment files (.env, backend/.env, and frontend/.env.local) to set the required secrets and configuration values (such as database URLs, API keys, etc.).

3. Install pre-commit hooks:

   pre-commit install
   

Starting the Application

1. Build the Docker images:

   task docker:build
   

2. Start all services:

   task docker:up
   

   Note: Wait for the frontend service to be fully running.

3. Generate frontend code based on the backend API:

   task frontend:codegen
   

4. Create an initial admin user:

   task backend:create-user
   

   Note: Follow the prompts. Use your email address as the username. You can leave the email field blank when prompted later.

5. The services will be available at:

   • Frontend Application
   • Backend Admin UI
   • Backend Health Check
   • GraphQL Endpoint (GraphiQL)

6. To stop and remove containers:

   task docker:down
   

⚙️ Development Tasks

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 backend and frontend services (such as linting, formatting, or testing).

To list all available tasks, run:

task --list

Refer to the README.md files in the backend and frontend directories for service-specific task details.

🧰 Troubleshooting

Frontend

If the frontend container crashes when installing dependencies:

1. Stop all services:

   task docker:down
   

2. Open a shell in a temporary frontend container:

   task frontend:bash
   

3. Inside the container, install the dependencies.
4. Build all services again:

   task docker:build
   

5. Start all services:

   task docker:up
   

🔄 CI/CD Workflows

This 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.

📦 Releases

All versioned changes are documented on the GitHub Releases page.

📄 License

This project is licensed under the MIT License.