{"id":30292430,"url":"https://github.com/vanajmoorthy/bibliotype","last_synced_at":"2026-02-09T20:09:45.000Z","repository":{"id":308442958,"uuid":"1029144727","full_name":"vanajmoorthy/bibliotype","owner":"vanajmoorthy","description":"Find out your bibliotype!","archived":false,"fork":false,"pushed_at":"2025-12-13T09:59:07.000Z","size":1192,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-14T09:47:27.933Z","etag":null,"topics":["alpinejs","data-analysis","django","goodreads"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vanajmoorthy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-30T15:33:25.000Z","updated_at":"2025-12-13T09:59:10.000Z","dependencies_parsed_at":"2025-08-27T00:14:43.822Z","dependency_job_id":"7f736d7c-a540-4423-a08c-09e416ff048f","html_url":"https://github.com/vanajmoorthy/bibliotype","commit_stats":null,"previous_names":["vanajmoorthy/bibliotype"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vanajmoorthy/bibliotype","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanajmoorthy%2Fbibliotype","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanajmoorthy%2Fbibliotype/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanajmoorthy%2Fbibliotype/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanajmoorthy%2Fbibliotype/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vanajmoorthy","download_url":"https://codeload.github.com/vanajmoorthy/bibliotype/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanajmoorthy%2Fbibliotype/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29279368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T19:05:41.198Z","status":"ssl_error","status_checked_at":"2026-02-09T19:05:37.449Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alpinejs","data-analysis","django","goodreads"],"created_at":"2025-08-17T00:33:55.113Z","updated_at":"2026-02-09T20:09:44.995Z","avatar_url":"https://github.com/vanajmoorthy.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧬 Bibliotype - Your Reading DNA (WIP)\n\nBibliotype is a web application that generates a personalised “Reading DNA” dashboard from a user's Goodreads or StoryGraph export file and provides visual insights into reading habits and preferences.\n\nThe app uses a Python backend with Pandas for data analysis and calls the Gemini API to generate a creative, AI-powered vibe for each user's unique reading taste.\n\nhttps://github.com/user-attachments/assets/41540178-f67a-4a48-9105-1a687f034c23\n\n\n## TODO\n- ⚠️⚠️⚠️⚠️⚠️⚠️⚠️\n- edit mainstream meter text to \"niche, normal, mainstream\"\n- make vibe look better with bg colours and fix dot separators and check mobile\n- forgot password email and email verification(?)\n- show user id in django admin\n- save recommendations as part of their profile\n- same with llm vibe\n- configure llm via posthog for tracking \n- check those little dot separators for vibe and improve vibe\n- fix redis cache issue\n- posthog\n  - track total number of profiles/unique bibliotypes generated\n  - get rid of recommendations_generated event\n  - add bibliotype generated event\n  - enable web capture and web vitals\n  - track redis cache error as error and not event\n- ⚠️⚠️⚠️⚠️⚠️⚠️⚠️\n- improve community stats look\n  - timelines/graphs for all community stats\n  - same for controversial ratings\n- long author names and genre names cutting of count when hovering on chart\n- allow user to delete profile\n- ✅ ~get rid of books per year~ \n- ^ make this like more granular month by month and scrollable and show genres in every month\n- ~ai text explanation of most controversial ratings and possible explanations~ \n- different colours for different reader types\n- pixel square background for banner\n- upload to instagram story\n- ai moodboard/collage. different options of things to upload to instagram \n- SEO stuff\n- adjust copy ⚠️\n- ui elements for community stats\n- update tests\n- add cron job to check publishers for mainstreamness\n- check lighthouse scores \n- add privacy statement? ToS\n- average \"contrarian\" score under most controversial ratings with phrases like \"my, you're contrarian\"\n- sign up form validate password and all on blur\n- how similar are you/similarity percentage for 2 or more people\n  - add page for this\n  - allow similarity comparison with multiple users (only public)\n- ~make pixelated dna strand logo~\n- add emojis in some places\n- think about more animation\n\n## ✨ Features\n\n- ** Data Analysis:** Ingests Goodreads export `.csv` files and performs detailed analysis using Pandas.\n- **AI-Powered Vibe:** Utilizes Google's Gemini API to generate a creative, multi-phrase \"vibe\" that poetically summarizes the user's reading taste.\n- **Analytics \u0026 Dashboard:**\n  - **Reader Archetype:** Assigns users a primary \"Reader Type\" (e.g., *Classic Collector*, *Tome Tussler*).\n  - **Core Stats:** Total books \u0026 pages read, average rating.\n  - **Community Benchmarking:** Compares user stats (like average book length and total books read) against the global Bibliotype user base, showing percentiles.\n  - **Taste Analysis:** Identifies top authors and genres, enriched with data from the Open Library API.\n  - **Niche vs. Mainstream:** Calculates a \"Mainstream Meter\" score and highlights the user's most niche book based on community read counts.\n  - **Review Insights:** Performs sentiment analysis on user reviews to find their most positive and negative takes.\n- **User Accounts \u0026 Sharing:**\n  - Full user authentication (signup with email, login, logout).\n  - Ability to save and update your Bibliotype to your profile.\n  - Publicly shareable profile pages (e.g., `bibliotype.com/u/username`).\n- **Performant \u0026 Scalable:**\n  - API calls are cached server-side using Django's cache framework.\n  - Caching logic prevents re-running expensive AI generation for unchanged data.\n  - Important user data is stored in indexed database fields for efficient querying.\n\n## 🛠️ Tech Stack\n\n- **Backend:** Django 5.x, Python 3.13+\n- **Dependency Management:** Poetry\n- **Data Processing:** Pandas\n- **AI Integration:** Gemini\n- **Database:** PostgreSQL (production), SQLite (fallback for non-Docker dev)\n- **Containerization:** Docker, Docker Compose\n- **Frontend:** Tailwind CSS, Alpine.js, Chart.js\n\n\n## 🚀 Getting Started (Docker \u0026 Poetry)\n\nThis is the recommended method for local development. It creates a consistent, isolated environment with a dedicated PostgreSQL database, mirroring a production setup.\n\n### 1. Prerequisites\n\n- Docker and Docker Compose\n- Poetry\n\n### 2. Installation \u0026 Setup\n\n1.  **Clone the repository:**\n    ```bash\n    git clone https://github.com/your-username/bibliotype.git\n    cd bibliotype\n    ```\n\n2.  **Create your environment file:**\n    Create a file named `.env` in the project root. This file is ignored by Git and will hold your secret keys.\n    ```env\n    # .env\n\n    SECRET_KEY=\"generate-a-new-secret-key\"\n    GEMINI_API_KEY=\"your-real-gemini-api-key\"\n\n    # Credentials for the local PostgreSQL container\n    POSTGRES_DB=bibliotype_db\n    POSTGRES_USER=bibliotype_user\n    POSTGRES_PASSWORD=yoursecurepassword123\n    ```\n\n3.  **Build and Run the Containers:**\n    From the project root, run the following command. The `-d` flag runs the services in the background.\n    ```bash\n    docker-compose -f docker-compose.local.yml up --build -d\n    ```\n\n### 3. Database Setup (First Time Only)\n\nThe first time you start the Docker environment, you need to set up the database. Open a **new terminal window** and run these commands:\n\n1.  **Apply Database Migrations:**\n    This command creates all the necessary tables in the new PostgreSQL database.\n    ```bash\n    docker-compose -f docker-compose.local.yml exec web poetry run python manage.py migrate\n    ```\n\n2.  **Load Initial Data:**\n    This command populates the database with a large catalog of books and pre-calculated community analytics from a local fixture file. This is the fastest way to get started.\n    ```bash\n    docker-compose -f docker-compose.local.yml exec web poetry run python manage.py loaddata core/fixtures/initial_data.json\n    ```\n\n3.  **Create a Superuser:**\n    This allows you to access the Django admin panel at `/admin/`.\n    ```bash\n    docker-compose -f docker-compose.local.yml exec web poetry run python manage.py createsuperuser\n    ```\n\nYou can now access the application at **`http://127.0.0.1:8000`**.\n\n#### Optional: Refreshing the Fixture File\n\nIf you update the book list in `seed_books.py` and want to regenerate the `initial_data.json` fixture, follow these steps:\n1.  `docker-compose -f docker-compose.local.yml down -v`\n2.  `docker-compose -f docker-compose.local.yml up --build -d`\n3.  `docker-compose -f docker-compose.local.yml exec web poetry run python manage.py migrate`\n4.  `docker-compose -f docker-compose.local.yml exec web poetry run python manage.py seed_books`\n5.  `docker-compose -f docker-compose.local.yml exec web poetry run python manage.py seed_analytics`\n6.  `docker-compose -f docker-compose.local.yml exec web poetry run python manage.py dumpdata core.Book core.Author core.Genre core.AggregateAnalytics --indent 2 \u003e core/fixtures/initial_data.json`\n7.  Commit the updated `initial_data.json` file to Git.\n\n## 🚀 Deploying to Production\n\nThis guide outlines the steps to deploy the application to a production environment on a fresh Ubuntu 22.04 server (e.g., a DigitalOcean VPS). The stack uses Docker Compose, Nginx as a reverse proxy, and GitHub Actions for fully automated CI/CD.\n\n### 1. Initial Server Setup\n\n1.  **Create an Ubuntu 22.04 Server:**\n    *   Provision a new VPS and ensure you can connect via SSH using your public key.\n\n2.  **Create a Deployment User:**\n    *   Log in as `root` and create a dedicated non-root user for the deployment.\n        ```bash\n        # Replace 'deploy' with your preferred username\n        adduser deploy\n        ```\n    *   Grant this user `sudo` privileges and add them to the `docker` group (this requires installing Docker first, see next step).\n        ```bash\n        usermod -aG sudo deploy\n        ```\n    *   Copy your SSH key to the new user so you can log in directly:\n        ```bash\n        # This command copies the keys from the root user\n        rsync --archive --chown=deploy:deploy ~/.ssh /home/deploy/\n        ```\n    *   Log out and log back in as your new `deploy` user.\n\n3.  **Install Software \u0026 Configure Firewall:**\n    *   Install Docker, Nginx, and Certbot.\n        ```bash\n        # Install Docker\n        curl -fsSL https://get.docker.com -o get-docker.sh\n        sudo sh get-docker.sh\n        sudo usermod -aG docker $USER # Add current user to docker group\n\n        # Install Nginx and Certbot\n        sudo apt update\n        sudo apt install nginx python3-certbot-nginx -y\n        ```\n    *   Configure the firewall to allow web and SSH traffic.\n        ```bash\n        sudo ufw allow OpenSSH\n        sudo ufw allow 'Nginx Full'\n        sudo ufw enable\n        ```\n    *   **Important:** Log out and log back in to apply the Docker group permissions. Verify with `docker ps`.\n\n### 2. Project Setup on the Server\n\n1.  **Clone the Repository:**\n    ```bash\n    git clone https://github.com/your-username/bibliotype.git app\n    cd app\n    ```\n\n2.  **Create the Production `.env` File:**\n    Create a new `.env` file for production secrets. **Use strong, unique credentials.**\n    ```bash\n    nano .env\n    ```\n    Paste and edit the following content:\n    ```ini\n    # .env (Production)\n\n    SECRET_KEY=\"...\"\n    GEMINI_API_KEY=\"...\"\n\n    POSTGRES_DB=bibliotype_prod_db\n    POSTGRES_USER=bibliotype_prod_user\n    POSTGRES_PASSWORD=\"...\"\n\n    DEBUG=False\n    ALLOWED_HOSTS=\"your_domain.com,www.your_domain.com\"\n    ```\n\n3.  **Create the Static Files Directory:**\n    This empty folder on the host will be mapped into the container so Nginx can access the collected static files.\n    ```bash\n    mkdir staticfiles\n    ```\n\n### 3. Nginx \u0026 SSL Configuration\n\n1.  **Create Nginx Config:**\n    Create a new configuration file for your site.\n    ```bash\n    sudo nano /etc/nginx/sites-available/bibliotype\n    ```\n    Paste the following configuration, replacing `your_domain.com` and `/home/deploy/app/` with your actual values.\n    ```nginx\n    server {\n        listen 80;\n        server_name your_domain.com www.your_domain.com;\n        return 301 https://$host$request_uri;\n    }\n\n    server {\n        listen 443 ssl http2;\n        server_name your_domain.com www.your_domain.com;\n\n        # Path for static files\n        location /static/ {\n            alias /home/deploy/app/staticfiles/;\n        }\n\n        # Proxy requests to the Django app\n        location / {\n            proxy_pass http://127.0.0.1:8000;\n            proxy_set_header Host $host;\n            proxy_set_header X-Real-IP $remote_addr;\n            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n            proxy_set_header X-Forwarded-Proto $scheme;\n        }\n\n        # SSL settings will be added by Certbot below\n    }\n    ```\n\n2.  **Enable the Site \u0026 Get SSL Certificate:**\n    *   Activate the configuration by creating a symlink.\n        ```bash\n        sudo ln -s /etc/nginx/sites-available/bibliotype /etc/nginx/sites-enabled/\n        ```\n    *   **Point your domain's DNS A records** to your server's IP address.\n    *   Run Certbot to obtain an SSL certificate and automatically update the Nginx config.\n        ```bash\n        sudo certbot --nginx -d your_domain.com -d www.your_domain.com\n        ```\n\n### 4. Setting Up GitHub Actions for CI/CD\n\n1.  **Create a Deploy-Specific SSH Key:**\n    On your **local machine**, create a new SSH key pair dedicated to this deployment. Do not use your personal key.\n    ```bash\n    ssh-keygen -t ed25519 -C \"github-deploy-bibliotype\" -f ~/.ssh/bibliotype_deploy_key\n    ```\n\n2.  **Add Public Key to Server:**\n    Copy the content of the **public key** (`cat ~/.ssh/bibliotype_deploy_key.pub`) and paste it as a new line in your server's `/home/deploy/.ssh/authorized_keys` file.\n\n3.  **Add Secrets to GitHub Repository:**\n    Go to `Your Repo \u003e Settings \u003e Secrets and variables \u003e Actions` and add the following repository secrets:\n    *   `DO_SSH_HOST`: Your server's IP address.\n    *   `DO_SSH_USERNAME`: Your deployment username (e.g., `deploy`).\n    *   `DO_SSH_KEY`: The content of the **private key** (`cat ~/.ssh/bibliotype_deploy_key`).\n    *   `DOCKERHUB_USERNAME`: Your Docker Hub username.\n    *   `DOCKERHUB_TOKEN`: A Docker Hub access token.\n\n4.  **Configure Passwordless `sudo`:**\n    The deployment script needs to fix file permissions. Allow your deploy user to run `sudo` without a password.\n    *   Run `sudo visudo` on your server.\n    *   Add this line at the very bottom of the file (replace `deploy` if you used a different username):\n        ```\n        deploy ALL=(ALL) NOPASSWD: ALL\n        ```\n\n### 5. First Deployment\n\nCommit your final `docker-compose.prod.yml`, `.github/workflows/deploy.yml`, and `settings.py` files to your repository and push to the `main` branch.\n\n```bash\ngit push origin main\n```\n\nThe GitHub Action will now run and automatically build, test, and deploy your application. Subsequent pushes to `main` will automatically update the live site.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanajmoorthy%2Fbibliotype","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvanajmoorthy%2Fbibliotype","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanajmoorthy%2Fbibliotype/lists"}