Magic Pinecone Backend 🌲

Note: This README file was generated by Gemini.

Welcome to the Magic Pinecone Backend! This is a backend API service project built with FastAPI, SQLAlchemy, and PostgreSQL. It aims to enable students at National Central University (NCU) to easily access and integrate a vast amount of campus information on a single platform.

🚀 Core Features

• FastAPI Driven: Provides a modern, high-performance Python web framework design.
• PostgreSQL Database: Supports a relational database for managing models such as courses, departments, and colleges.
• Docker Containerization: Includes the application, database, and Digirunner via docker-compose, making infrastructure configuration and deployment effortless.
• Course Finder Fetching: Built-in functionality for automatically / manually synchronizing the latest course data from the school system.
• Scheduling: Automatically handles background scheduled tasks via APScheduler.

---

📚 Course Finder Fetching

One of the key features of this backend is its ability to fetch and parse course data from the NCU campus system, synchronizing and storing the data in a local PostgreSQL database to enable fast queries and reads.

Mechanism: The scraper uses httpx to retrieve data for each college and department from the school's course system (including parsing XML-formatted course details and fetching HTML page course attributes using BeautifulSoup). It then batches, merges, and updates (UPSERTs) the latest information into the database.

Ways to Trigger Synchronization:

1. Scheduled Automatic Updates: Integrated with APScheduler within the FastAPI lifecycle events, it defaults to automatically triggering a course data fetch and sync in the background every day at 04:00 AM.
2. Manual API Trigger: For immediate updates, you can send a POST request to the /course/sync route. This uses FastAPI's BackgroundTasks to start the course synchronization process in the background, allowing you to get an API response without waiting for the scraper to finish executing.

---

🛠️ Getting Started

Prerequisites

• Docker & Docker Compose
• (Optional) Local development can use uv (This project requires Python 3.13+)

Quick Start with Docker (Recommended)

Using Docker Compose is the easiest way to start up. It will launch your Backend API, PostgreSQL database, and Digirunner Gateway by default.

1. Environment Variables Configuration: Copy the example environment variable file and modify it according to your needs.

   cp example.env .env

2. Start All Services:

   docker-compose up -d --build

3. Access the Services:

   • Backend API Host: http://localhost:8000
   • FastAPI (Swagger) Documentation: http://localhost:8000/docs
   • Digirunner Gateway: http://localhost:18080

Local Development Setup (Without Docker)

If you want to run and debug directly in your own local development environment:

1. Create the environment and install dependencies (managed by pyproject.toml or uv.lock).

   uv sync

2. Prepare a local PostgreSQL database, and set the corresponding DB connection environment variables (e.g., DB_USER, DB_PASSWORD, and DB_NAME) in .env.
3. Start the FastAPI development server using Uvicorn.

   uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000

---

🏆 Acknowledgments

Special thanks to the following project for providing implementation inspiration and reference for the course scraper feature of this backend:

• Course Finder Fetcher: NCU-Course-Finder-DataFetcher-v2