Skip to content

Dima-Bulavenko/wordnest

BranchesTags

Repository files navigation

WordNest (Milestone Project 4)

Responsive Mockup

WordNest Online Dictionary is a personal project aimed at creating bilingual dictionaries to help with language learning and translation. I believe that language learning should be a personalized and engaging experience, and the Wordnest is designed to provide the tools and resources you need to succeed.

Table of contents

Table of contents generated with markdown-toc

Purpose

The WordNest Online Dictionary is built using the Django framework, which provides robust backend functionality, including user authentication, data management, and routing. The frontend is enhanced by Django's templating system to deliver a seamless and interactive user experience. Additionally, the integration of htmx allows for dynamic content updates without the need for full page reloads, further enhancing the user experience by making interactions smoother and more responsive.

Key features of the platform include personalized dictionary creation, custom translations, instant translations, and quick word searches. These features are designed to provide an engaging and efficient tool for language learners and enthusiasts.

Table of contents

UX Design

Target audiences:

  • Language Learners and Enthusiasts: Individuals passionate about learning new languages and expanding their vocabulary. These users can benefit from the personalized dictionary and custom translation features.
  • Students and Educators: Students looking for a tool to aid their language studies and educators seeking a resource to support their teaching. WordNest can be a valuable addition to their learning and teaching toolkit.
  • Bilingual and Multilingual Individuals: People who speak or are learning multiple languages and need a reliable tool to manage and translate vocabulary across languages.

Epics

To craft an epic logic on GitHub, I begin by creating an issue and assigning it the "Epic" label. Within this issue, I meticulously compile a list of both user and developer stories that are integral to the epic's completion.

You can find all the epics here

User and Developer Stories

Back to the top

Wireframes

All wireframes were created using figma. The wireframes are designed to provide a visual representation of the website's layout and functionality across different screen sizes.

Welcome page

  • Mobile Mobile wire frame
  • Laptop

Home page

  • Mobile Mobile wire frame
  • Laptop alt="Laptop wire frame">

Profile page

  • Mobile Mobile wire frame
  • Laptop alt="Laptop wire frame">

Dictionary page

  • Mobile Mobile wire frame
  • Laptop alt="Laptop wire frame">

Form page

  • Mobile Mobile wire frame
  • Laptop alt="Laptop wire frame">

Back to the Top

Agile Development

In this project, we use Agile methodology to manage and track development tasks. Here's a breakdown of how we apply Agile practices:

Task Management

  • Issues: Each task is represented by an issue in our GitHub repository.
  • Labels: Issues are categorized using labels to indicate their priority and importance:
    • Could Have
    • Must Have
    • Should Have
    • Would Have
  • Milestones:
    • Product Backlog: This milestone includes all issues that have been identified but not yet assigned to a specific iteration. Issues in this milestone do not have time constraints.
    • Iteration #number: Each iteration has a specific duration (one week) and is assigned a milestone. Issues are moved to this milestone as they are scheduled for the current iteration.

Project Management

  • GitHub Kanban Board: We use a GitHub Kanban board to represent the current iteration's state and to track progress. Each iteration has its own project board.
  • Iteration Planning: For each new iteration, a new project board is created. Each iteration consists of a specific number of issues that are planned for completion within the week.

Workflow

  1. New Issues: All new issues are added to the Product Backlog milestone by default.
  2. Iteration Setup: When a new iteration begins, a new project board is created, and issues from the Product Backlog are selected and moved to the corresponding Iteration #number milestone.
  3. Execution: During the iteration, the team works on issues as per the priority labels and tracks progress on the GitHub Kanban board.
  4. Review: At the end of each iteration, completed issues are reviewed, and a new iteration is planned with updated priorities and tasks.

This structured approach ensures clear task prioritization and efficient tracking of progress throughout the development cycle.

Design

Color Scheme

This color scheme was chosen to create a clean and modern look for the website.

Color Scheme

Typography

This project uses the following Google Font:

  • Inter - for all text content.

Back to the top

Features

User Registration and Authentication

This project utilizes the Django allauth library to handle user registration, authentication, and account management, including social account integration.

  • Registration and Authentication with Social Accounts: Allows users to sign up and log in using social accounts.
  • User Registration: Enables new users to create an account with their details.
  • User Login: Provides users with the ability to log in using their credentials.
  • User Logout: Allows users to log out from their accounts.
  • Reset Password: Facilitates the process for users to reset their forgotten passwords.
  • Change Password: Allows users to change their account passwords.
  • Set Password: Allows users to set a password for their account if they sign up with their social account.
  • Email Confirmation: Sends a confirmation link to the user's email to verify that the email address belongs to the user.
  • User Account Deletion: Allows users to permanently delete their accounts.
  • Admin Model Registration: Registers models in the Django Admin interface for administrative purposes.

Dictionary Management

  • Add Word to Dictionary: Users can add new words to their personal dictionaries.
  • Delete Dictionary: Provides functionality for users to delete entire dictionaries.
  • Delete Word from Dictionary: Allows users to remove specific words from their dictionaries.
  • Create User Dictionaries: Enables users to create and manage their own custom dictionaries.
  • Look Up Words on the Fly: Users can perform real-time lookups for words within the dictionary.
  • Create Own Translation: Allows users to create and store their own translations for words.

Backend and API Integration

  • API Translations Added to Database: Ensures that translations retrieved from external APIs are stored in the application's database.
  • Search Database Before API: Searches for translations in the database before querying external APIs for efficiency.
  • Distinguish API and User Translations: Differentiates between translations sourced from APIs and those created by users.
  • API Translations with AZURE Translation API: Implements translation features using the AZURE Translation API to provide accurate and reliable translations.

User Profile and Notifications

  • User Profile: Provides users with a profile page where they can view and update their personal information.
  • Success and Error Toast Notifications: Displays toast messages to inform users of success or errors during interactions.

Dynamic and Interactive Features

  • Infinite Word Scroll in User Dictionary: Implements infinite scrolling for viewing words in the user's dictionary, enhancing navigation.
  • Dynamic Word Management with HTMX: Allows users to delete, create, and search for words within their dictionaries without a full page refresh. Utilizes HTMX for seamless, real-time updates to the dictionary interface.

Database Schema

The first schema is for the dictionary app, which includes models for dictionaries, words, and translations. The second schema is for the entire project, which includes models for user profiles, user dictionaries, and user translations.

Database Schema of dictionary app Database Schema of dictionary app
Database Schema of whole project Database Schema of whole project

Back to the top

Testing

Manual Testing

Navbar

  • ✔️ Navbar layout displays correctly on different screen sizes.
  • ✔️ All links are working correctly.
  • ✔️ The burger menu functions correctly on mobile devices.
  • ✔️ Anonymous users do not see links that are only for authenticated users.

Footer

  • ✔️ Footer layout displays correctly on different screen sizes.
  • ✔️ All links are working correctly.
  • ✔️ The link to the GitHub repo opens in a new tab.

Home page

  • For anonymous users:

    • ✔️ The home page displays correctly on different screen sizes.
    • ✔️ All links are working correctly.
    • ✔️ Shows Sign Up button.
    • ✔️ Shows Sign up with Google and Facebook icons.
    • ✔️ Shows "Features" section.

  • For authenticated users:

    • ✔️ All links are working correctly.
    • ✔️ Shows dictionaries list.
    • ✔️ Shows Create dictionary button.
    • ✔️ Shows Delete dictionary icon near each dictionary.

Dictionary page

  • For anonymous users:

    • ✔️ Get redirect to the welcome page.

  • For authenticated users:

    • ✔️ All links are working correctly.
    • ✔️ The dictionary page displays correctly on different screen sizes.
    • ✔️ User can add, delete and search words.

Profile page

  • For anonymous users:

    • ✔️ Get redirect to the welcome page.

  • For authenticated users:

    • ✔️ All links are working correctly.
    • ✔️ The dictionary page displays correctly on different screen sizes..
    • ✔️ User can change the password.
    • ✔️ User can delete the account.
    • ✔️ User can seen general information about his account.
    • ✔️ User can see amount of his dictionaries and delete them.

Forms

All forms were created using one template so that they have the same styles and functionality. An anonymous user can see all forms except Set Password, Change Password, and Create Dictionary forms.

  • For all users:
    • ✔️ All forms are displayed correctly on different screen sizes.
    • ✔️ All form fields, buttons, and hints work correctly.

Back to the top

Unit testing

Python unit tests

Unit tests was create with django built-in django test functionality. To run the tests, run the following command in the terminal:

python manage.py test
Test results: Python unit tests
Test coverage: Python test coverage

JS unit tests

JS unit testing was performed through Jest. To run the tests, run the following command in the terminal:

npm test wordnest/static/js/__tests__/
Test results: JavaScript unit tests

Back to the top

Code validation

HTML Validation

To validate the HTML code, I use the W3C HTML Markup Validator. Since I use htmx in my project, the validator will show some errors related to the htmx attributes, but these can be ignored.

CSS Validation

To validate the CSS code, I use the W3 Jigsaw validator.

Python Validation

To validate the Python code I use Ruff VScode extension.

  • ✔️ No errors found.

JS Validation

To validate the JS code I use [ESLint] VScode extension(https://eslint.org/).

  • ✔️ No errors found.

Back to the top

Lighthouse

  • Profile page Profile page
  • Dictionary page Dictionary page
  • Set Password page Set Password page
  • Change password page Change password page

Back to the top

Technologies

Languages

  • Python+Django, JavaScript, HTML, CSS

Programs, frameworks, libraries

Back to the top

Environment Variables

To run this project locally, you will need to create a .env file in the root directory of the project and add the following environment variables:

SECRET_KEY=your_django_secret_key
DEBUG=True
DB_NAME=
DB_USER=
DB_PASSWORD=
DB_HOST=
DB_PORT=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
FACEBOOK_CLIENT_ID=
FACEBOOK_CLIENT_SECRET=
AZURE_TRANSLATOR_KEY=

GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, FACEBOOK_CLIENT_ID, FACEBOOK_CLIENT_SECRET used for user social authentication.

AZURE_TRANSLATOR_KEY used to translate words with API.

Deployment

Heroku

The WordNest project was deployed on a Heroku hosting server. The following steps outline the process of deploying the WordNest project and can be applied to deploy another Django project with minor adjustments:

  1. Navigate to your Heroku dashboard and create a new app with a unique name.

  2. Install decouple to manage environment variables.

    pip install python-decouple

    Note: Decouple is a useful library that allows you to separate local and production settings for Django projects.

  3. Create a .env file in the root directory of your project.

  4. Add the following text to .gitignore file. This makes git ignore .env file.

    .env

  5. Add DEBUG=True to the .env file.

  6. Import decouple in the settings.py.

    from decouple import config

  7. Replace DEBUG variable in the settings.py with the following code:

    DEBUG = config("DEBUG", default=False, cast=bool)

  8. Install gunicorn as a production-ready webserver for Heroku with command.

    pip install gunicorn

  9. Create a file named Procfile at the root directory of the project.

  10. Add following command to Procfile to run your server in production.

    web: gunicorn wordnest.wsgi

    Note: Replace wordnest with your project name

  11. In the settings.py file update the ALLOWED_HOSTS variable.

    ALLOWED_HOSTS = ['127.0.0.1', '.herokuapp.com']

  12. Install dj-database-url.

    pip install dj-database-url

  13. Import dj-database-url in settings.py.

    import dj_database_url

  14. Install psycopg2 to connect to PostgreSQL database.

    pip install psycopg2

  15. In the settings.py replace DATABASES with the following code:

    if DEBUG:
    DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": config("DB_NAME"),
        "USER": config("DB_USER"),
        "PASSWORD": config("DB_PASSWORD"),
        "HOST": config("DB_HOST"),
        "PORT": config("DB_PORT"),
        }
    }
else:
    DATABASES = {
        'default': dj_database_url.parse(config('DATABASE_URL'))
    }

    Note: Replace if clause with your own database for local development

  16. In the .env file update the DEBUG environment variable and add DATABASE_URL new one.

    DEBUG=False
DATABASE_URL=add_URL_of_a_remote_database

    Note: For the WordNest I used database URL provided by Code Institute but you can use other database hosting services< such as Amazon RDS for PostgreSQL/sub>

  17. Reload your terminal and run the following command in terminal to migrate remote database.

    python manage.py migrate

  18. Replace DEBUG=False to DEBUG=True in the .env file.

  19. Return to the Heroku dashboard navigate to the Settings tab and click on Reveal Config Var and add DATABASE_URL environment variable.

  20. Install whitenoise to manage static files on production server.

    pip install whitenoise

  21. Add whitenoise to the MIDDLEWARE list in the settings.py.

    MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    'whitenoise.middleware.WhiteNoiseMiddleware',
]

    Note: The WhiteNoise middleware must be placed directly after the Django SecurityMiddleware

  22. Add STATIC_ROOT and STORAGES variables to the settings.py.

    STORAGES = {
    "staticfiles": {
        "BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage",
    },
}
STATIC_ROOT = BASE_DIR.joinpath("staticfiles")

  23. Run the following command in terminal to collect static files.

    python manage.py collectstatic

  24. From the terminal, check the Python version used in your IDE.

    python --version

  25. Look up the supported runtimes here and copy the runtime closest to the one used in your IDE.

  26. Add a runtime.txt file to your app's root directory.

  27. Paste the copied runtime into the runtime.txt file.

  28. Update requirements.txt.

    pip freeze > requirements.txt

  29. Add and commit all changes to the repository.

    git add .
git commit -m "Deploying to Heroku"

  30. Push the changes to your remote branch that you intend to deploy.

    git push

  31. On the Heroku dashboard, and in your app, click on the Deploy tab.

  32. In the Deployment method section enable GitHub integration by clicking on Connect to GitHub.

  33. Start typing your project repo name into the search box and click Search. A list of repositories from your GitHub account should appear. Click on the GitHub repo you want to deploy from.

  34. Scroll to the bottom of the page in the Manual deploy section, choose branch you want to deploy and click Deploy Branch to start a manual deployment of the branch.

  35. Open the Resources tab and choose an eco dyno. This dyno is a lightweight container to run your project.

  36. Verify there is no existing Postgres database add-on. if there is a database add-on select Delete Add-on to remove it.

  37. Click on Open app to view your deployed project.

Back to the top

Clone GitHub Repo

  1. Log into your account on GitHub
  2. Go to the repository of this project WordNest
  3. Click on the code button, and copy your preferred clone link.
  4. Open the terminal in your code editor and change the current working directory to the location you want to use for the cloned directory.
  5. Type git clone into the terminal, paste the link you copied in step 3 and press enter.

Back to the top

Bugs

  • All fixed bugs can be found here

  • All unfixed bugs can be found here

Back to top

Credits

Media

Back to the top

Design Template

Back to the top

Code

Back to the top

Acknowledgements

I want to convey my immense gratitude to my mentor, Luke Buchanan, for pinpointing my mistakes and providing advice on how to rectify them. Special thanks to my friends who assisted in testing the application, and to the Slack community, always ready to offer valuable tips at any time.

Back to the top

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Languages