huyphan2025 / alps-aws-huy

Advanced Language Practices (ALPs)

Improve your language skills with inspiring images & immediate feedback!

---

Now that you've "climbed the mountain" of learning another language, keep your skills fresh with regular practice! Language output (speaking & writing) is key but can get dull with routine drills, plus you may never know if it's entirely correct.
🔸
With ALPs, every writing challenge comes with an inspiring image to ignite your imagination, a random verb & grammar points to help focus your language, and immediate feedback with the help of AI!

---

Table of Contents

1. About The Project
   • Agile Methodology
   • Built With
2. Getting Started
   • Prerequisites
   • External API Keys
   • Schema
   • Testing
3. Endpoints
4. External APIs
5. Stretch Technologies
6. Future Iterations
7. Contributors

About the Project

🔸 [Production Website] (add link here)
🔸 Backend Service
🔸 Front End Repository

[Video Presentation] (EMBED VIDEO HERE)

ALPs was created by a cross-functional development team of students from the Turing School of Software and Design as their capstone project.

The mission of ALPs is to provide users with writing promts that ignite their imagination and provide immediate feedback on their language output.

Users simply choose their target language via an avatar to start a new challenge. When they begin, they'll see a random verb, inspiring image, and multiple grammar points to create fresh, unique sentences. Once they submit the challenge -- with the help of AI -- immediate feedback and correct sentences are provided so they can review and learn even faster! Users also have the option to email a copy of their work to themselves since tracking personal progress not only expediates growth but also cultivates confidence!

Agile Methodology

This method is a flexible and iterative approach to project management that focuses on collaboration, adaptability, and continuous improvement.

The agile methodology was chosen for backend development to expedite the app's launch and progressively abstract functions across multiple phases of development.

Built With

Phase 1: Delivered Minimum Viable Product (MVC)

Phase 2: Refactored Deployment

• Replaced: With:

Phase 3: Abstracted Functionality with Additional Stretch Technologies

(back to top)

Getting Started

If you'd like to demo this API on your local machine:

1. Ensure you have the prerequisites
2. Sign up for external API Keys
3. Clone this repo: git clone [email protected]:A-L-P-s/ALPs_api.git
4. Navigate to the root folder: cd ALPs_api
5. Run: bundle install
6. Run: rails db:{create,migrate,seed}
7. Run: bundle exec figaro install
8. In the app/config/application.yml file add you API keys:

• UNSPLASH_API_KEY: add_api_key_here
• OPENAI_API_KEY: add_api_key_here

1. Inspect the /db/schema.rb and compare to the 'Schema' section below to ensure migration has been done successfully
2. Run: rails s
3. Visit http://localhost:3000/

Prerequisites

• Ruby Version 3.1.1
• Rails Version 7.0.4.x
• Bundler Version 2.4.9

External API Keys

Sign up for your individual external API keys:

• Unsplash Image API
  • Follow instructions provided.
• OpenAI API
  • Once you have signed up, click on your profile at the top left and selecting View API keys.
  • Then click Create new secret key.

Schema

Phase 1:

Phase 2:

[Add second image] (when schema changes to microservices)

Testing

To test the entire spec suite, run bundle exec rspec. All tests should be passing.

Happy path, sad path, and edge case testing were considered and tested. When a request cannot be completed, an error object is returned.

See Error Object

    
{
  "errors": [
    {
      "status": "404"
      "title": "Invalid Request",
      "detail": "Couldn't find User with 'id'="
     }
   ]
}
    

Status Codes

See All

ALPs API reutrns the folowing status codes:

Status Code	Description
200	OK
201	CREATED
204	NO CONTENT
404	NOT FOUND
418	I'M A TEAPOT
422	UNPROCESSABLE CONTENT
500	INTERNAL SERVER ERROR

(back to top)

Endpoints

GET "/api/v1/users"

Response:

Code	Description
200	OK

    
{
  "data": [{
    "id": "55",
    "type": “user",
    "attributes": {
        "name": "Deniz",
        "preferred_lang": "Turkish",
        "challenges": null (or [])
    }},
    {
    "id": "1",
    "type": “user",
    "attributes": {
        "name": "Alexis",
        "preferred_lang": "Spanish",
        "challenges": null (or [])
      }
  }]
}
  

GET "/api/v1/users/:id"

Response:

Code	Description
200	OK

    
{
  "data": {
    "id": “55”,
    "type": “user",
    "attributes": {
        "name": "Deniz",
        "preferred_lang": "Turkish",
        "challenges": [
            {
              "challenge_id": "1", 
              "language": "Turkish", 
              "verb": "(i) gitmek",
              "eng_verb": "to go", 
              "image_url": "/random/unplash/image.url",
              "image_alt_text": "Plane flying over the Bosphorous", 
              "created_at": "05-30-2023"
            }, 
            { ...etc...}
        ]
     }  
   }
}
    

GET "/api/v1/users/:id/challenges/new"

Response:

Code	Description
200	OK

    
{
  "data": {
    "id": null,
    "type": “challenge",
    "attributes": {
        "language": "Turkish", 
        "verb": "(i) gitmek"
        "eng_verb": "to go" 
        "image_url": "/random/unplash/image.url"
        "image_alt_text": "Plane flying over the Bosphorous" 
        "created_at": null
        "grammar_points": [
           {
            "grammar_point": "geçmiş zaman"
            "eng_grammar_point": "past simple"
           },
           { ...etc...}
        ]
        "sentences": null
     }  
   }
}
    

POST "/api/v1/users/:id/challenges"

Request Body:

    
{
 "language": "Turkish",
 "verb": "(i) gitmek",
 "eng_verb": "to go",
 "image_url": "/random/unplash/image.url",
 "image_alt_text": "Plane flying over the Bosphorous", 
 "sentences": [
   {
    "grammar_point": "geçmiş zaman",
    "eng_grammar_point": "past tense",
    "user_sent": "Dün havalimana gittik ama arkadaşım uçak gelmedi."
    },
    {
      "grammar_point": "geniş zaman",
      "eng_grammar_point": "future tense",
      "user_sent": "Dün havalimana gittik ama arkadaşım uçak gelmeyecek."
    }
  ]
}
    
  

Response:

Code	Description
201	CREATED

    
  {
  "data": {
    "id": “1”,
    "type": “challenge",
    "attributes": {
        "language": "Turkish", 
        "verb": "(i) gitmek",
        "eng_verb": "to go", 
        "image_url": "/random/unplash/image.url",
        "image_alt_text": "Plane flying over the Bosphorous", 
        "created_at": "05-30-2023",
        "grammar_points": null,
        "sentences": [
          {
           "sent_id": "1",
           "grammar_point": "geçmiş zaman",
           "eng_grammar_point": "past tense",
           "user_sent": "Dün havalimana gittik ama arkadaşım uçak gelmedi.",
           "ai_sent": "Dün havalimanına gittik, ancak arkadaşımızın uçağı gelmedi."
           }, 
           { ...etc...}     
         ]
     }  
   }
}
    

GET "/api/v1/users/:id/challenges/:challenge_id"

Response:

Code	Description
200	OK

    
{
  "data": {
    "id": “1”,
    "type": “challenge",
    "attributes": {
        "language": "Turkish", 
        "verb": "(i) gitmek",
        "eng_verb": "to go", 
        "image_url": "/random/unplash/image.url",
        "image_alt_text": "Plane flying over the Bosphorous", 
        "created_at": "05-30-2023",
        "grammar_points": null,
        "sentences": [
          {
           "sent_id": "1",
           "grammar_point": "geçmiş zaman",
           "eng_grammar_point": "past tense",
           "user_sent": "Dün havalimana gittik ama arkadaşım uçak gelmedi.",
           "ai_sent": "Dün havalimanına gittik, ancak arkadaşımızın uçağı gelmedi."
           }, 
           { ...etc...}     
         ]
     }  
   }
}
    

DELETE "/api/v1/users/:id/challenges/:challenge_id"

Response:

Code	Description
204	NO CONTENT

View these endpoints in [Postman] (add link here)

(back to top)

External APIs

Unsplash Image API

- Used to generate the random theme image for every writing challenge.

OpenAI API

- Used to correct sentences and provide immediate feedback on user's language output.

(back to top)

Stretch Technologies

Elastic Beanstock Deployment

- Phase 2: Amazon Web Services was used to deploy the application.

Python Programming Language

- Phase 3: Used as the programming language to build microservices.

Django Web Framework

- Phase 3: Used as the web framework to build microservices.

Twilio/Sendgrid Email Service

- Phase 3: Used to allow users to email themselves a copy of their completed challenge.

(back to top)

Future Iterations

See Refactoring Suggestions

🔸 Add authorization & authentication

- Allow users to create own profile and dashboard

🔸 Expand AI functionality

- Add questions/quizes created by AI for language topics

- Create and save flashcards

🔸 Create administrative role

- Track statistics of all users and languages

(back to top)

Contributors

Kirk Hauck	Bea Ordonez	Katherine Blaine	Tyalor Pridgen	Brian Zanti
FrontEnd	FrontEnd	FrontEnd	Project Mentor	Project Manager
GitHub	GitHub	GitHub	GitHub	GitHub
LinkedIn	LinkedIn	LinkedIn	LinkedIn	LinkedIn

Caleb Thomas	James Taylor	Huy Phan	David Marino	Melony Erin Franchini
BackEnd	BackEnd	BackEnd	BackEnd	BackEnd
GitHub	GitHub	GitHub	GitHub	GitHub
LinkedIn	LinkedIn	LinkedIn	LinkedIn	LinkedIn

(back to top)