authsec_firstAPI/README.md

# AuthSec FastAPI - Base Project for Python

A production-ready, modular **FastAPI** backend that serves as a direct drop-in alternative to the Spring Boot base project (`authsec-be`).

It provides **identical API contracts and endpoint paths** so that frontends like **Angular Clarity** or **React** can communicate with it without modifying any frontend code.

---

## 🌟 Key Features

- **100% Endpoint Parity with Spring Boot**:
  - `POST /token/session` - User login and JWT session generation
  - `GET /token/logout` - User logout
  - `GET /token/user` - Currently authenticated user details
  - `GET /fndMenu/menuloadbyuser` - Hierarchical role-based menu tree for Angular Clarity sidebar
  - `GET`, `POST`, `PUT`, `DELETE` for `/{{TABLE}}` and `/{{TABLE_LOWER}}` - Entity CRUD endpoints
- **Zero-Setup Database**: Runs on **SQLite** out of the box with automatic table creation & seeding on startup. Switchable to MySQL or PostgreSQL by simply editing `DATABASE_URL` in `.env`.
- **Pre-Seeded Accounts**: Comes with a default administrator account:
  - **Email**: `admin@cns.com`
  - **Password**: `admin123`
- **Dynamic Entity Router**: Any generated entity controller placed in `app/io8ref/*/controllers.py` is automatically registered upon startup.
- **Interactive Swagger UI**: Full interactive API documentation available at `http://localhost:9119/docs`.

---

## 🚀 Quick Start (First Time on Windows)

### Step 1: Install Python
If you don't have Python installed on your machine:
1. Download Python 3.11 or 3.12 from [python.org/downloads](https://www.python.org/downloads/).
2. Run the installer.
3. ⚠️ **IMPORTANT**: Check the box **"Add python.exe to PATH"** at the bottom of the first installer screen before clicking *Install Now*.

### Step 2: Open PowerShell in Project Directory
Open PowerShell in `d:\WAP\Codeextractor\authsec-fastapi`:
```powershell
cd d:\WAP\Codeextractor\authsec-fastapi
```

### Step 3: Create and Activate Virtual Environment
```powershell
# Create a virtual environment named venv
python -m venv venv

# Activate it
.\venv\Scripts\Activate.ps1
```
*(If PowerShell shows an execution policy error, run `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass` and then run the activate command again).*

### Step 4: Install Dependencies
```powershell
pip install -r requirements.txt
```

### Step 5: Run the Server
```powershell
python run.py
```

The server will start on:
- **API URL**: `http://localhost:9119`
- **Interactive Swagger Documentation**: `http://localhost:9119/docs`

---

## 📡 API Contract Reference

### 1. Authentication
- **`POST /token/session`** (or `POST /token/generate-token`)
  - **Request Body**:
    ```json
    {
      "email": "admin@cns.com",
      "password": "admin123"
    }
    ```
  - **Response Payload**:
    ```json
    {
      "operationStatus": "SUCCESS",
      "operationMessage": "Login Success",
      "item": {
        "userId": 1,
        "email": "admin@cns.com",
        "fullname": "Admin User",
        "firstName": "Admin",
        "username": "admin",
        "roles": ["Admin"],
        "token": "eyJhbG..."
      }
    }
    ```
- **`GET /token/logout`**
- **`GET /token/user`** (with `Authorization: Bearer <token>`)

### 2. Menu Navigation
- **`GET /fndMenu/menuloadbyuser`**
  - Returns root navigation items with their respective sub-menus, action paths, and icons formatted for the Angular layout.

### 3. Entity CRUD Operations
Every entity (such as reference entity `Azzu`) provides both uppercase and lowercase endpoints:
- `POST /Azzu` or `POST /azzu` - Add new record
- `GET /Azzu` or `GET /azzu` - Get all records
- `GET /Azzu/{id}` or `GET /azzu/{id}` - Get record by ID
- `PUT /Azzu/{id}` or `PUT /azzu/{id}` - Update record by ID
- `DELETE /Azzu/{id}` or `DELETE /azzu/{id}` - Delete record by ID

---

## 🛠️ Code Extractor V2 Integration

The pack configuration file is located at [`pack-fastapi-v1.0.json`](./pack-fastapi-v1.0.json).

When Code Extractor generates a new entity (e.g. `Customer`), it produces:
1. `app/io8ref/Customer/models.py` - SQLAlchemy entity model
2. `app/io8ref/Customer/schemas.py` - Pydantic DTO schema
3. `app/io8ref/Customer/services.py` - Business logic and database operations
4. `app/io8ref/Customer/controllers.py` - REST API routes

Because `app/main.py` has automatic discovery enabled, the new entity endpoints are instantly active without needing any manual code registration.