Skip to content

digitalinnovationone/acceleration-a11y-clean-restful-apis

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

19 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Accessibility (A11y) in Clean RESTful APIs

Discover how to combine the concepts of Clean Architecture with the Speech-To-Text (STT) concept to promote accessibility for audible educational content and harness the power of Java, Spring Boot, and MongoDB in building a RESTful API focused on accurate audio transcription.

Presentation slides available here: DIO Acceleration: Accessibility in Clean RESTful APIs

Hands-On Overview

The Audio2Text project is an advanced system designed to transcribe audio content into text format, leveraging the power of OpenAI's API for high-quality transcriptions. The project follows Clean Architecture principles to ensure a scalable, maintainable, and well-organized codebase.

Project Structure and References

This project's architecture is inspired by and references several key sources in Clean Architecture and software design. The structure is visualized using a mermaid graph for clarity.

graph RL;
  subgraph "Infrastructure";
    Web(Web & Devices) <--> Con
    UI("User Interface (UI)") <--> Pre
    DB(Databases & External Integrations) <--> Gat

    subgraph "Adapters";
      Con(Controllers) <--> UC
      Pre(Presenters) <--> UC
      Gat(Gateways) -..-> |implements| IGat

      subgraph "Use Cases";
        UC(Use Cases) <--> LA
        UC <--> IGat

        subgraph "Entities";
          LA("Learning Objects (LOs)")
          LA -.- LOA[<em>Metadata includes:\n Transcript, Language,\n Revision, License etc.</em>]
          IGat(Gateway Interfaces)
          IGat -.- IRep(<em>Any external integrations:\n Database, WebClient,\n Producer etc.</em>)
        end
     end
    end
  end

classDef infra fill:#a3c9ff,stroke:#00315c,color:#00315c;
classDef adapters fill:#67dbb1,stroke:#003828,color:#003828;
classDef ucs fill:#ffb1c1,stroke:#5f112b,color:#5f112b;
classDef entities fill:#e2c54b,stroke:#3a3000,color:#3a3000;
classDef entities_secondary fill:#fff0c0,stroke:#3a3000,color:#3a3000;

class Web,Dev,UI,DB,EXT infra;
class Con,Gat,Pre adapters;
class UC ucs;
class LA,IGat entities;
class LOA,IRep entities_secondary;

Loading

Key References and Inspirations:

Development Demands (TODOs)

Our development team has outlined several key TODOs for further implementation and integration:

Environment Setup

TODO 1. Check/Create the mandatory environment variables!

Code built hands-on:

# DONE! 1. Check/Create the mandatory environment variables!

Integration with OpenAI API to High-Quality Transcription

OpenAI API Reference: https://platform.openai.com/docs/api-reference/audio/createTranscription

TODO 2. Respecting the TranscriptionService contract, consumes POST "audio/transcription" on OpenAI API!

Code built hands-on:

// DONE! 2. Respecting the TranscriptionService contract, consumes "audio/transcription" on OpenAI API!

TODO 3. Orchestrate the integration with transcription service.

Code built hands-on:

Accessibility Showcase

VLibras Widget Reference: https://vlibras.gov.br/doc/widget/installation/webpageintegration.html

TODO 4. Using the JS Fetch API, consumes GET "/transcribed-audios/{id}" locally and show the transcript.

Code built hands-on:

// DONE! 4. Using the JS Fetch API, consume GET "/transcribed-audios/{id}" and display transcript.

TODO 5. Integrate with VLibras: https://vlibras.gov.br/doc/widget

Code built hands-on:

<!-- DONE! 5. Integrate with VLibras: https://vlibras.gov.br/doc/widget -->