[GSSoC'26] : Fixed-Backend-Issues

[janmejay1438]

Fix Backend Initialization, Package Imports, Dependency Resolution, and Local Development Stability

Closes #754
I would recommend reading the contribution.md file i have included a part where running the backend is explained properly. @devanshi14malhotra I think you will be able to get a lot of this pr from there. I have also added successful screenshots of api testing below. Maam, This PR only contains all the relevant changes. I hope you find all the changes to your liking.
Thank you so much, maam.

Overview

This PR resolves multiple backend setup and runtime issues that prevented the BiblioDrift Flask backend from running successfully in a modern local development environment using Python 3.12.

The fixes primarily focus on:

• stabilizing backend startup
• correcting Python package/module resolution
• fixing internal import structure
• resolving dependency issues
• improving local development experience
• enabling successful API endpoint testing
• configuring LLM integration
• improving backend maintainability

---

Problems Identified

While setting up the backend locally, several critical issues were encountered:

Package & Import Issues

• ModuleNotFoundError for multiple internal backend modules
• inconsistent import structure across backend services
• inability to run backend using package execution mode

Examples:

ModuleNotFoundError: No module named 'backend'
ModuleNotFoundError: No module named 'sanitizer'
ModuleNotFoundError: No module named 'exceptions'
ModuleNotFoundError: No module named 'validators'

---

Dependency Issues

Missing runtime dependencies caused backend initialization failures.

Example:

ModuleNotFoundError: No module named 'PIL'

---

Configuration & Environment Issues

• missing environment validation
• invalid database initialization
• JWT configuration issues
• local SQLite path issues

---

Flask Runtime Instability

Flask debug auto-reloader caused repeated crashes/restarts on Windows during heavy AI imports.

Examples:

WinError 10038
KeyboardInterrupt during OpenAI/Gemini imports

---

Security Middleware Blocking Local Testing

CSRF protection prevented testing API endpoints locally using:

• Thunder Client
• Postman
• curl

---

Changes Made

---

1. Converted Backend Into Proper Python Package

Added:

backend/__init__.py

This enables correct package execution:

python -m backend.app

instead of relying on directory-based execution.

---

2. Fixed Internal Backend Imports

Updated backend imports to use package-qualified module paths.

Examples:

from sanitizer import sanitize_payload

→

from backend.sanitizer import sanitize_payload

Similar fixes applied across multiple backend modules including:

• validators
• exceptions
• config
• cache_service
• error_responses
• ai_service
• reader_identity
• price_tracker
• middleware-related imports

This resolved repeated module resolution failures.

---

3. Added Missing Pillow Dependency

Added missing image-processing dependency:

Pillow

to:

requirements.txt

This resolved:

ModuleNotFoundError: No module named 'PIL'

and ensured backend image utilities initialize correctly.

---

4. Fixed Dataclass Configuration Initialization

Resolved configuration initialization issues by ensuring config classes were properly structured for constructor-based initialization.

This fixed runtime errors such as:

TypeError: EmailConfig() takes no arguments

---

5. Stabilized Flask Development Runtime

Updated Flask startup configuration to disable unstable auto-reloader behavior during local development.

Updated:

app.run(...)

to:

app.run(
    debug=False,
    use_reloader=False,
    host=server_config.host,
    port=server_config.port
)

This resolved:

• repeated reload loops
• Windows socket errors
• repeated heavy AI imports
• runtime instability during development

---

6. Fixed SQLite Local Database Initialization

Updated local database configuration for reliable development startup.

Configured:

DATABASE_URL=sqlite:///bibliodrift.db

I just wasnot able to do it inside the instance folder so did this.
This resolved:

sqlite3.OperationalError: unable to open database file

---

7. Added Development-Only CSRF Handling

Added conditional CSRF bypass for development mode only:

if os.getenv("APP_ENV") == "development":
    app.config["WTF_CSRF_ENABLED"] = False

This enables:

• local API testing
• Thunder Client/Postman requests
• frontend integration testing

while preserving production security behavior.

---

Endpoints Verified

Health Endpoint

GET /api/v1/health

Verified:

• backend health
• configuration validation
• cache initialization
• service startup

---

Chat Endpoint

POST /api/v1/chat

Verified:

• request validation
• AI response generation
• JSON serialization
• successful Gemini integration

---

Mood Search Endpoint

POST /api/v1/mood-search

Verified:

• schema validation
• request handling
• recommendation generation
• successful response flow

---

Environment Used

• Python 3.12
• Flask
• SQLite
• Gemini API
• Windows
• Git Bash
• Thunder Client (For API testing)

---

Notes

• Mood analysis endpoints remain disabled due to optional NLP dependencies not being installed.
• favicon-related 404 errors are unrelated to backend functionality.

---

Result

Backend now:

• starts successfully
• Initializes configuration correctly
• resolves internal imports properly
• supports stable local development
• allows API testing locally
• integrates successfully with Gemini
• exposes working REST endpoints
• operates correctly under Python 3.12

[netlify]

✅ Deploy Preview for bibliodrift-dm ready!

Name	Link
🔨 Latest commit	3326e4f
🔍 Latest deploy log	https://app.netlify.com/projects/bibliodrift-dm/deploys/6a110462b8aa01000878d248
😎 Deploy Preview	https://deploy-preview-819--bibliodrift-dm.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Wahid7852]

This PR is definitely addressing problems but it is a problem in itself too because the scope became too broad. lol.

Some of the import cleanup changes make sense (backend.* package-qualified imports, __init__.py, missing Pillow dependency, etc.), but other changes are much more opinionated/risky for the project as a whole.

A few concerns:

• Disabling CSRF in development mode inside app initialization is still a security-sensitive change and should probably be discussed separately instead of bundled into a generic “backend fixes” PR.
• Changing default DB paths/config behavior can affect existing local setups unexpectedly.
• Forcing debug=False and use_reloader=False directly in app.run() overrides existing environment-driven config behavior instead of fixing the underlying reload/import issue cleanly.
• There are also still unresolved branch conflicts.

[janmejay1438]

@Wahid7852, Appreciate your concern. I had concern myself. But my sole goal upon working on this issue became that i just need to first get the backend to a running a state. Later if there are any imporvements people think they can do. They are welcomed. @Wahid7852 If you believe you can improve it later on maybe do that. Also i will look into conflicts.

Thank you so much sir. I will definitely look into these facts and make sure that the pr is up to everyone's standard.
Thank you so much sir. I will fix the above concerns given by @Wahid7852

[janmejay1438]

@devanshi14malhotra Mam, Upon close inspection maybe it will be better if i leave the backend to get fixed by the maintainers themselves. I would love to contribute on it further somehow Closing this pull request. Thank you so much for your time.