Design Documents

1. Document Revision History

Version	Date	Description
1.0.0	03 Oct 2025	First Draft
1.1.0	04 Oct 2025	Fill the basic design documents
1.1.1	05 Oct 2025	Add Pictures and details
2.1.0	19 Oct 2025	Fix Backend Class Diagram/DB Model
3.1.0	02 Nov 2025	Fix Testing Plan, Update System Architecture, Add Data Pipeline Class Diagram
4.0.0	16 Nov 2025	Fix Architecture, Class Diagram
5.0.0	30 Nov 2025	Update BE/Data Pipeline Class Diagram, DB Diagram, Recommendation Algorithm
5.0.1	30 Nov 2025	Update Testing Plan
5.0.2	02 Dec 2025	Update Testing Results

2. System Design

2.1. System Architecture

2.2. Class Diagrams and Data Models

2.2.1. Android Class Diagram

The frontend class diagram consists of mainly three kind of classes.

• Activity: MainActivity is the startpoint of the app. It is responsible for redirecting to AppNavHos which navigates to all pages.

• View Models: There are ViewmMdels containing functions and UiStates connecting API and views (Screens). Route connects ViewModels and Views, and Repository connects API and ViewModels. These ViewModels handle and send almost every logics and states for each Views.

• Composables: There are various composables rendering corresponding pages layouts. (diagram blocks with @Composable tag)

2.2.2. Backend Class Diagram

The presented class diagram illustrates the architecture for customized program recommendation services, and the core is comprised of two independent primary entities, User and Program. The User class vectorizes and stores user preferences, including personal information and economic eligibility requirements (household_income, birth_date), as well as preference_embedding, and the Program class details the application period, operating entity, and detailed eligibility criteria (eligibility_min_income, eligibility_max_age) and provides the data needed for AI matching, including embedding of program content. These two classes are connected in a many-to-many relationship through a connection class called Bookmark and ProgramLike, which records the user's explicit interests, which supports a highly personalized matching system that collects user behavior data, compares user qualifications and program criteria, and simultaneously performs embedding-based similarity recommendations.

2.2.3. Data Pipeline Class Diagram

The data pipeline class diagram consists of mainly three kind of classes.

• Loader: Fetches raw data (HTML/JSON) from government websites and APIs.

• Vectorizer: Converts content into embedding vectors.

• PostgresManager: Saves data to the PostgreSQL database.

2.2.4. DB Model

DB Schema

• The program_example is for the initial user preference.
• The feed_cache is the programs' recommendation order for a user.
• postcode_mapping is for the User-Program address matching.

2.3. Recommendation Algorithm

We designed the following recommendation algorithm during Iteration 4. The implementation is not yet complete and is scheduled to be finished in the next iteration.

Overall Recommendation Process

Stage 1: Candidate Generation

1. A "User x Program" Two-Tower Model is used to perform an initial ranking.
2. This stage filters the entire list down to the Top 300 most relevant programs for the user.

Stage2: Re-ranking (Detailed Scoring)

1. Parallel Scoring: The 500 programs are evaluated by three separate Two-Tower Models based on specific user interactions:

   • "Liked" Program x Program: Generates score L
   • "Bookmarked" Program x Program: Generates score B
   • "See Less" Program x Program: Generates score S

2. Metric Calculation: A final score (Metric) is calculated for each program using a weighted formula. This formula combines the new scores (L, B, S) with the original score from Stage 1 (U):

   Metric = w_l*L + w_b*B + w_u*U - w_s*S

3. Final Selection: The 500 programs are ordered by this final metric, and the Top 300 Ordered Programs are selected as the final recommendation list.

3. Testing Plan

• Our testing strategy for '잇다' is designed to validate both the technical architecture and the core business value: providing reliable, highly personalized policy information. We focus on ensuring the robustness of our MVVM architecture on the frontend and the performance of our API services on the backend.

3.1. Unit Testing & Integration Testing

• The objective is to validate that each software unit performs as designed and that different modules work correctly together, particularly the data flow between the UI layer and the backend.

• Who: The coder responsible for each feature/page writes its tests. Frontend test code is reviewed by the frontend team, and backend test code is reviewed by the backend team.

• When:

  • Frontend: Run the full test suite locally before every commit.
  • Backend: Run at ci for every push/pr.

Target	Framework & Tools	Objective & Scope	Coverage Goal
Frontend (Android App)	JUnit 4, MockK, Espresso	To validate the business logic within the ViewModel layer. Integration tests will verify the crucial interactions between ViewModels and the Repository, ensuring correct API communication and robust data flow throughout the app. Scope includes visibility, operations, and contents of UI elements like buttons and text fields.	>85% (Focus on critical ViewModel logic and data flow)
Backend (Spring Boot/Kotlin)	Spring Boot Test, JUnit 5, MockMvc	To validate API endpoints and the core business logic within the Service layer. Integration tests will verify authentication, profile management, and essential data operations, ensuring secure and reliable service delivery.	>80% (Focus on critical authentication, profile logic, and all service layer transactions.)

3.2 Acceptance Testing

The following 5 user stories have been selected for User Acceptance Testing (UAT). These user stories are defined in detail in our Requirements & Specifications document.

Selected User Stories for UAT:

1. User Story 5.1.2: Personalized Policy Recommendation

• As a senior looking for welfare benefits, I want to view personalized welfare policies based on the personal information I entered, so that I can quickly find the policies I need.
  • Given the users are signing up, When they enter and select their personalized characteristics, Then they can see the personalized program recommendation on the home page.

2. User Story 5.1.3: Policy Details and AI Summary

• As a user who finds complex policy documents difficult to understand, I want to view AI-generated summaries and well-organized detailed information on the policy detail page, so that I can easily understand the policy and determine my eligibility.
  • Given A user is interested in a specific policy from the policy feed, When The user taps on a policy card, Then Policy Detail page with AI-generated summary is displayed along with well-organized detailed information including eligibility requirements, application methods, and deadlines.

3. User Story 5.1.4: Keyword Search and Result Sorting

• As a user looking for specific welfare benefits, I want to search for policies by entering keywords and sort results by relevance or recency, So that I can quickly find the information I need.
  • Given A user is on the search page, When The user selects a recommended keyword chip or enters a keyword in the search bar and searches, Then A list of relevant policies is displayed, sorted by relevance or recency.

4. User Story 5.1.5: Bookmark Management

• As a user who wants to compare multiple policies, I want to bookmark policies of interest and view them later, So that I can revisit and compare them when needed.
  • Given the user is viewing a program card / program detail page, When they tap the bookmark icon, Then the policy is saved to a dedicated bookmark screen.

5. User story 5.1.6 Accessibility Settings

• As a senior user with poor vision, I want to adjust font size and enable dark mode on the profile page, So that I can use the app in a comfortable environment for my eyes.
  • Given A user is in the settings menu on the profile page, When The user changes font size or dark mode settings, Then The changes are immediately applied throughout the entire app.

For detailed acceptance criteria with Given-When-Then scenarios, please refer to the respective sections in the Requirements & Specifications document.

3.3 Testing Result

• Frontend

Test Type	Scope	Description
Unit Test	Screen-specific ViewModels: state reducers, input validation, mapping/parsing, side-effect triggers, error/loading states, navigation intents.	We unit-test by decomposing each screen’s ViewModel into granular responsibilities and verifying each behavior with mocked repositories and coroutine test utilities.
Integration Test	Verify ViewModel↔Repository interactions, correct API mapping and error propagation, state→UI rendering, navigation intents, and caching/retry behavior.	Run with real/fake repositories and mocked network cases (success/failure/latency) to assert UiState transitions, UI behavior, side effects, and navigation outcomes.

• Frontend Unit Test Result

• Frontend Integration Test Result

• Backend

Test Type	Scope	Description
Unit Test	Service Layer Logic (e.g., Password hashing/verification, User creation/update, Custom validation logic)	Verify individual service methods using mocked repository/external components to isolate and test specific business rules and exceptions (SignUpEmailConflictException, LogInInvalidPasswordException, etc.).
Integration Test	Controller/API Endpoints (Authentication, Profile: /api/v1/auth/signup, /api/v1/my-profile, etc.)	Use MockMvc to simulate end-to-end HTTP requests. Assert correct HTTP status codes (200 OK, 400 Bad Request, 409 Conflict, etc.), response schema, and persistent state changes (user creation, profile update).

• Backend Test Result(11/30)