# albertemb/filmadvisor architecture

> Architecture diagram of the GitHub repository albertemb/filmadvisor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/albertemb/filmadvisor
- Repository: https://github.com/albertemb/filmadvisor

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“FilmAdvisor”) built with:
- A TypeScript/React-style frontend (Vaadin Hilla)
- A Java/Spring Boot backend
- AWS DynamoDB and PostgreSQL as data stores
- External services (Streaming Availability API, IMDb)
- Purpose: Let users browse, filter, discover, and track movies across streaming platforms.

##### File Structure
- Top-level split:
- src/main/frontend → client-side UI
- src/main/java → server-side Spring Boot application
- docs/ → design docs, data import scripts, UML
- pom.xml, mvnw → Maven build
- tsconfig.json, vite.config.ts, package.json → frontend build
- Backend layout:
- amb.config → DynamoDB config
- amb.movie, amb.user, amb.userMovieStatus → domain entities, endpoints, repositories (impl + interface)
- Frontend layout:
- components, views, context, model, data, themes, types
- Vaadin Hilla connects TS code to secure Java endpoints automatically.
- Config files:
- application.properties (Spring Boot)
- DynamoDBConfig.java
- vite.config.ts, tsconfig.json (frontend bundling)

##### Extract Additional Insights from README
- Tech stack details (Java 21, Spring Boot 3.4.3, Vaadin 24.6.6, DynamoDB, PostgreSQL)
- Features (filters, random discovery, tracking status)
- Deployment instructions (mvnw, packaging)

a. Main Components
- User’s Browser / Frontend
- Vaadin Hilla UI Layer (React/TS components)
- Hilla Endpoints (auto-generated TypeScript ↔ Java bridges)
- Spring Boot Application Layer (Controllers/Services)
- Repositories & Data Access
- Datastores: AWS DynamoDB (movie metadata) & PostgreSQL (user profiles)
- External Services: Streaming Availability API, IMDb API
- Dev/Test Tools (import scripts, sample data, test suite)

b. Relationships & Data Flow
1. User interacts with Browser → Vaadin UI Components (FilterPanel, MovieCard, etc.)
2. UI calls Hilla Endpoints (e.g., MovieEndpoint, UserEndpoint)
3. Endpoints invoke Service/Repository layer in Spring Boot
4. Repositories read/write to DynamoDB or PostgreSQL
5. For streaming info or ratings, backend makes HTTP calls to external APIs
6. Responses bubble back through the same chain to the UI

c. Architectural Patterns & Design Principles
- Layered architecture (UI → API → Service/Repo → DB)
- Dependency injection via Spring Boot
- Repository pattern for DB access
- Context & state management in frontend (FilterContext)
- IaC/config layering (application.properties, DynamoDBConfig)

d. Key Technologies & Frameworks
- Frontend: Vaadin Hilla, React-style TS components, Vite
- Backend: Spring Boot, Java 21, Hilla secure endpoints
- DBs: AWS DynamoDB SDK, Spring Data (PostgreSQL)
- External HTTP clients (Streaming API, IMDb)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Tier
    subgraph "Frontend Tier"
        direction TB
        Browser["User's Browser"]:::frontend
        Index["index.html"]:::frontend
        TSConfig["tsconfig.json"]:::frontend
        ViteConfig["vite.config.ts"]:::frontend

        subgraph "UI Components"
            direction TB
            FilterPanel["FilterPanel"]:::frontend
            MovieCard["MovieCard"]:::frontend
            MovieFilter["MovieFilter"]:::frontend
            MovieSelector["MovieSelector"]:::frontend
        end

        Context["FilterContext"]:::frontend
        ModelMovie["Movie.ts"]:::frontend
        TypePanelProps["PanelProps.ts"]:::frontend

        subgraph "Data & Assets"
            direction TB
            GenresData["genres.json"]:::frontend
            MoviesData["movies.json"]:::frontend
            MovieCardCSS["MovieCard.css"]:::frontend
            StylesCSS["styles.css"]:::frontend
            ThemeJSON["theme.json"]:::frontend
            IconsDir["icons"]:::frontend
            ImagesDir["images"]:::frontend
        end

        subgraph "Views & Routing"
            direction TB
            ViewIndex["@index.tsx"]:::frontend
            ViewLayout["@layout.tsx"]:::frontend
            ViewLogin["Login.tsx"]:::frontend
        end
    end

    %% Backend Tier
    subgraph "Backend Tier"
        direction TB
        Application["Application.java"]:::backend

        subgraph "Hilla Endpoints"
            direction TB
            MovieEndpoint["MovieEndpoint"]:::backend
            UserEndpoint["UserEndpoint"]:::backend
            UserMovieStatusEndpoint["UserMovieStatusEndpoint"]:::backend
        end

        subgraph "Configuration"
            direction TB
            DynamoConfig["DynamoDBConfig.java"]:::backend
            AppProperties["application.properties"]:::backend
        end

        subgraph "Domain Entities"
            direction TB
            EntityMovie["Movie.java"]:::backend
            EntityUser["User.java"]:::backend
            EntityStatus["UserMovieStatus.java"]:::backend
        end

        subgraph "Repositories"
            direction TB
            MovieRepo["MovieRepositoryImpl"]:::backend
            UserRepo["UserRepositoryImpl"]:::backend
            StatusRepo["UserMovieStatusRepositoryImpl"]:::backend
        end

        DynamoDB["AWS DynamoDB"]:::datastore
        PostgreSQL["PostgreSQL"]:::datastore
    end

    %% External Services
    StreamingAPI["Streaming Availability API"]:::external
    IMDbAPI["IMDb API"]:::external

    %% Connections - Frontend to Backend
    Browser --> FilterPanel
    Browser --> MovieCard
    Browser --> MovieFilter
    Browser --> MovieSelector
    FilterPanel --> MovieEndpoint
    MovieCard --> MovieEndpoint
    MovieFilter --> MovieEndpoint
    MovieSelector --> MovieEndpoint
    Context --> MovieEndpoint
    Context --> UserEndpoint
    Context --> UserMovieStatusEndpoint

    %% Backend internal flows
    MovieEndpoint --> MovieRepo
    UserEndpoint --> UserRepo
    UserMovieStatusEndpoint --> StatusRepo

    MovieRepo --> DynamoDB
    UserRepo --> PostgreSQL
    StatusRepo --> PostgreSQL

    %% External calls
    MovieEndpoint -.-> StreamingAPI
    MovieEndpoint -.-> IMDbAPI

    %% Click Events - Frontend
    click Index "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/index.html"
    click TSConfig "https://github.com/albertemb/filmadvisor/blob/dynamodb/tsconfig.json"
    click ViteConfig "https://github.com/albertemb/filmadvisor/blob/dynamodb/vite.config.ts"
    click FilterPanel "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/components/FilterPanel.tsx"
    click MovieCard "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/components/MovieCard.tsx"
    click MovieFilter "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/components/MovieFilter.tsx"
    click MovieSelector "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/components/MovieSelector.tsx"
    click Context "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/context/FilterContext.tsx"
    click ModelMovie "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/model/Movie.ts"
    click TypePanelProps "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/types/PanelProps.ts"
    click GenresData "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/data/genres.json"
    click MoviesData "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/data/movies.json"
    click MovieCardCSS "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/themes/MovieCard.css"
    click StylesCSS "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/themes/filmadvisor/styles.css"
    click ThemeJSON "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/themes/filmadvisor/theme.json"
    click IconsDir "https://github.com/albertemb/filmadvisor/tree/dynamodb/src/main/resources/META-INF/resources/icons"
    click ImagesDir "https://github.com/albertemb/filmadvisor/tree/dynamodb/src/main/resources/META-INF/resources/images"
    click ViewIndex "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/views/@index.tsx"
    click ViewLayout "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/views/@layout.tsx"
    click ViewLogin "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/frontend/views/Login.tsx"

    %% Click Events - Backend
    click MovieEndpoint "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/java/amb/movie/MovieEndpoint.java"
    click UserEndpoint "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/java/amb/user/UserEndpoint.java"
    click UserMovieStatusEndpoint "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/java/amb/userMovieStatus/UserMovieStatusEndpoint.java"
    click Application "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/java/amb/Application.java"
    click DynamoConfig "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/java/amb/config/DynamoDBConfig.java"
    click AppProperties "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/resources/application.properties"
    click EntityMovie "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/java/amb/movie/Movie.java"
    click EntityUser "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/java/amb/user/User.java"
    click EntityStatus "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/java/amb/userMovieStatus/UserMovieStatus.java"
    click MovieRepo "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/java/amb/movie/MovieRepositoryImpl.java"
    click UserRepo "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/java/amb/user/UserRepositoryImpl.java"
    click StatusRepo "https://github.com/albertemb/filmadvisor/blob/dynamodb/src/main/java/amb/userMovieStatus/UserMovieStatusRepositoryImpl.java"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#000,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#000,stroke-width:1px
    classDef datastore fill:#ffe5b4,stroke:#000,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#000,stroke-width:1px
```
