Nehzn is a production-ready FastAPI backend for an AI-powered travel platform focused on North East India. It features Nera, an AI travel guide that helps users discover hidden gems, plan trips, and explore the diverse cultures of the region.

• Nera AI Chat: Real-time conversational interface with state management.
• Streaming WebSockets: Instant AI responses with text streaming for a premium feel.
• Semantic Search: Destination discovery powered by pgvector and OpenAI embeddings.
• Clean Architecture: Modular structure designed for scalability.
• Infrastructure: Automated migrations with Alembic and containerized services with Docker.

graph TD
    User((Traveler))
    Frontend[Vite + React]

    subgraph "Nehzn Backend (FastAPI)"
        WS[WebSocket / REST API]
        Nera[Nera Core Service]
        AI[AI Service Layer]
    end

    subgraph "Data & State"
        DB[(PostgreSQL + pgvector)]
        Redis[(Redis)]
    end

    OpenAI[[OpenAI API]]

    User <-->|Real-time Chat| Frontend
    Frontend <-->|WebSockets/HTTP| WS
    WS <--> Nera
    Nera <--> AI
    AI <--> OpenAI
    Nera <--> DB
    Nera <--> Redis

stateDiagram-v2
    [*] --> START: New Session

    state START {
        direction TB
        G1: "Hi! I'm Nera."
        B1: [Plan a trip]
        B2: [Discover places]
        B3: [Just exploring]
    }

    START --> INTERESTS: Clicked [Plan a trip]

    state INTERESTS {
        direction TB
        G2: "What sparks your interest?"
        B4: [Nature & Landscapes]
        B5: [Local Culture]
        B6: [Adventure]
    }

    INTERESTS --> RECOMMENDATIONS: Clicked Interest

    state RECOMMENDATIONS {
        direction TB
        G3: "Based on that, I suggest..."
        D1: [View Destination Cards]
        B7: [Refine Search]
    }

    RECOMMENDATIONS --> PLANNING: Selected Destination
    PLANNING --> [*]: Complete

• Framework: FastAPI (Python 3.11+)
• Database: PostgreSQL with pgvector
• ORM: SQLModel (SQLAlchemy + Pydantic)
• Real-time: WebSockets
• AI: OpenAI (GPT-4o-mini & Text Embeddings)
• Cache/State: Redis
• Migrations: Alembic

• Python 3.11+
• Docker & Docker Compose

# Clone the repository
git clone <your-repo-url>
cd nehzn_backend

# Install dependencies (modern TOML setup)
pip install -e .

Copy .env.example to .env and add your keys:

OPENAI_API_KEY=your_key_here
DATABASE_URL=postgresql+asyncpg://postgres:pass@localhost:5432/postgres
REDIS_URL=redis://localhost:6379

If you want to run a local database and Redis, use:

# Start DB and Redis
docker-compose up -d db redis

# Run migrations
alembic upgrade head

Option A: Native (Recommended for Dev)

uvicorn app.main:app --reload

Option B: Docker (Standalone) If your .env has cloud database/redis URLs, you can run only the server in Docker:

docker-compose up backend

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Connect to: ws://localhost:8000/api/v1/ws/{session_id}

Send: {"message": "Hello Nera!"} Receive:

• chunk: Incremental text streaming.
• final: Completed response with structured UI blocks and updated state.

app/
├── api/             # API Endpoints (v1)
├── core/            # Configuration & Logging
├── db/              # Database Models & Session
├── modules/         # Business Logic (Nera, AI, Travel)
└── schemas/         # Pydantic Schemas

Developed with ❤️ for the North East.