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

cd d:\WAP\Codeextractor\authsec-fastapi

Step 3: Create and Activate Virtual Environment

# 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

pip install -r requirements.txt

Step 5: Run the Server

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:

    {
      "email": "admin@cns.com",
      "password": "admin123"
    }
    

  • Response Payload:

    {
      "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.

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.