# Nanda Arch 🚀

> An opinionated backend framework, built on FastAPI and Tortoise ORM, designed to accelerate the development of robust and scalable APIs in Python.

Inspired by the productivity and modular structure of Django, but with all the power and modernity of the asynchronous ecosystem.

---

## ✨ Philosophy

Nanda Arch was created to solve common problems at the beginning of backend projects by providing an organized structure and out-of-the-box tools, allowing you to focus on what truly matters: your application's business logic.

---

## 🔑 Key Features

- 🚀 **Productive CLI**: Create new projects and apps with the `nanda startproject` and `nanda startapp` commands.
- 📦 **Modular Architecture**: Organize your code into independent "apps," just like in Django.
- ⚡ **Fully Asynchronous**: Take full advantage of the performance of FastAPI and Tortoise ORM.
- 🔒 **Security Included**: A built-in security template with JWT (token creation and validation) and a role-based permission system ready to use.
- ⚙️ **Environment-based Settings**: Configuration management with `python-decouple`, separating code from environment variables (`.env`).
- 🗄️ **Database Migrations**: Integrated with Aerich to manage your database schema migrations effortlessly.

---

## 📋 Requirements

- Python 3.13+
- Poetry

---

## 🛠️ Framework Installation

To start using Nanda Arch to create your own projects, first install the framework itself:

```bash
# 1. Clone the repository
git clone https://github.com/your-username/nanda-arch.git

# 2. Navigate into the directory
cd nanda_arch-arch

# 3. Install dependencies and the 'nanda_arch' command
poetry install
````

---

## 🚀 Quick Start: Creating Your First Project

Let's create a project from scratch in under 5 minutes.

### 1. Create the Project

Use the `nanda` command we just installed:

```bash
nanda_arch startproject my-awesome-project
```

### 2. Set Up the Environment

Navigate into the newly created project folder. You will find a `.env` file ready to be configured.

```bash
cd my-awesome-project
```

Open the `.env` file and set your `JWT_SECRET_KEY`. This is a critical security step. You can generate a strong key with the following command:

```bash
# This command generates a secure key. Copy and paste it into your .env file
openssl rand -hex 32
```

### 3. Install Project Dependencies

Each project generated by Nanda Arch has its own dependencies. Install them:

```bash
poetry install
```

### 4. Create Your First App

Let’s create an app to manage users:

```bash
nanda_arch startapp users
```

### 5. Register the App

Open the `system/settings.py` file and add your new app to the `INSTALLED_APPS` list:

```python
# system/settings.py

INSTALLED_APPS = [
    'apps.users.config',  # Add this line
]
```

### 6. Prepare the Database

Nanda Arch uses Aerich for migrations.

```bash
aerich init -t <your settings>

# Initializes Aerich, connecting it to Tortoise ORM
aerich init-db

# Creates the first migration file based on your models
aerich migrate --name "initial"

# Applies the migration, creating the tables in the database
aerich upgrade
```

### 7. Run the Server!

Everything is ready! Start the development server:

```bash
uvicorn main:app --reload
```

Open your browser to [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) to see the interactive API documentation!

---

## 🏗️ Generated Project Structure

A project created with `nanda startproject` will have the following structure:

```
my-awesome-project/
├── apps/                 # Where your modular apps will live
├── system/               # The core of your project
│   ├── core.py           # Main FastAPI instance and app registry
│   ├── security.py       # Authentication logic, JWT, and permissions
│   └── settings.py       # Project settings (apps, database, etc.)
├── .env                  # Environment variables (NEVER commit this!)
├── .gitignore            # Files to be ignored by Git
├── main.py               # Entrypoint for the Uvicorn server
├── pyproject.toml        # Project dependencies and settings
└── README.md             # Your project's documentation
```

---

## 📄 License

This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for more details.

---

## ❤️ A Personal Note

This project is dedicated with all my love to my girlfriend, **Mirelly Fernanda**, in celebration of our first year together. The name "Nanda" is a tribute to her.

— Made with love, Jefferson 💻

