Skip to content

Commit 35f9acb

Browse files
fullenifulleni
committed
docs: create project README
- Updated memory bank - Included product vision and license details
1 parent b12b5cc commit 35f9acb

File tree

7 files changed

+177
-37
lines changed

7 files changed

+177
-37
lines changed

‎README.md

Lines changed: 80 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,80 @@
1-
# Ht Main
1+
# 📰 Headlines Toolkit
2+
3+
## 📖 Overview
4+
5+
**Headlines Toolkit** is a source-available, full-stack Flutter application designed to provide a foundation for building news apps. It offers a streamlined, user-friendly experience for browsing news headlines and is built with a clean, maintainable architecture. Developers can freely evaluate the source code and run the app locally for a 32-day trial period. A commercial license is required for any use beyond this trial, including continued local use, modification, production use, or distribution.
6+
7+
## ✨ Features
8+
9+
- 🗞️ **Headlines Feed:** Displays a minimalist list of news headlines (title only, with source, category, and country represented as icons).
10+
- 📃 **Headline Details Page:** Provides detailed information about a headline (title, image, source, category, date, and a "Continue Reading" button that opens the original article in the browser).
11+
- 🔎 **Search:** Allows users to search for headlines.
12+
- 🗂️ **Filtering:** Allows users to filter headlines by category, source, and event country.
13+
- 🌗 **Dark Mode:** Supports light and dark themes.
14+
- 📅 **Planned Features:**
15+
- 👥 User accounts/profiles
16+
- 🌟 Personalized recommendations
17+
- 💾 Saving articles
18+
- 📵 Offline Reading
19+
- 🔔 Push notifications
20+
- 📰 News categories/topics
21+
- 🚀 Social sharing
22+
- 💬 Comments/discussion features
23+
24+
## 🛠️ Technical Overview
25+
26+
- 🎯 **Language:** Dart
27+
- 💙 **Framework:** Flutter
28+
- 🧱 **State Management:** BLoC
29+
- 🔀 **Routing:** go_router
30+
- ⚙️ **Backend:** Firebase (current), Supabase (future)
31+
- 🏛️ **Architecture:** Layered architecture (Data, Repository, Business Logic, Presentation)
32+
- 💉 **Dependency Injection:** Manual
33+
- ⚖️ **Licensing:** Source-available under the PolyForm Free Trial License for evaluation. Commercial license required for production use, distribution, or continued use beyond 32 days.
34+
35+
## ⚖️ License
36+
37+
This project is source-available under the [PolyForm Free Trial License 1.0.0](LICENSE). This license allows for free evaluation of the Headlines Toolkit source code and local execution of the application for up to 32 consecutive days. Any use beyond this trial period, including continued local use, modification, production use, or distribution, requires a commercial license.
38+
39+
## 💰 Commercial License
40+
41+
A commercial license covers all repositories within the Headlines Toolkit organization, including the backend and any related packages. This provides licensees with a complete, full-stack solution for building their news applications. The commercial license grants developers the rights to use the source code in production, customize it to their needs, and distribute their derived applications.
42+
43+
## 🚀 Getting Started
44+
45+
1. **Clone the repository:**
46+
47+
```bash
48+
git clone https://github.com/headlines-toolkit/ht-main
49+
```
50+
2. **Navigate to the project directory:**
51+
52+
```bash
53+
cd ht-main
54+
```
55+
3. **Get dependencies:**
56+
57+
```bash
58+
flutter pub get
59+
```
60+
4. **Run the app (development flavor):**
61+
62+
```bash
63+
flutter run -t lib/main_development.dart
64+
```
65+
66+
This will run the app using the in-memory data client.
67+
68+
## 🗂️ Project Structure
69+
70+
The project is organized using a feature-based directory structure within the `lib` folder:
71+
72+
```
73+
lib/
74+
├── app/ # Main application widget, app-level BLoCs, and views
75+
├── headlines-feed/ # Headlines feed feature
76+
├── headlines-search/ # Headlines search feature
77+
├── l10n/ # Localization files
78+
├── router/ # Routing configuration
79+
└── shared/ # Reusable widgets and utilities
80+
```

‎memory-bank/activeContext.md

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,15 @@
22

33
## Current Focus
44

5-
Updating the memory bank to reflect the addition of the headlines search feature and associated route updates.
5+
Creating the project README.
66

77
## Recent Changes
88

9-
- Added the `headlines-search` feature:
10-
- Created `headlines-search/bloc/headlines_search_bloc.dart`, `headlines_search_event.dart`, and `headlines_search_state.dart`.
11-
- Created `headlines-search/view/headlines_search_page.dart` and `headlines_search_view.dart`.
12-
- Updated the router (`lib/router/router.dart` and `lib/router/routes.dart`) to include the search route.
9+
- Updated the memory bank to reflect the full product vision and licensing details.
1310

1411
## Next Steps
1512

16-
- Continue updating the memory bank.
13+
- Implement the planned features and integrate the backend (Firebase, with future Supabase support).
1714

1815
## Active Decisions
1916

‎memory-bank/productContext.md

Lines changed: 42 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,57 @@
11
# Product Context
22

3+
## Project Name
4+
5+
Headlines Toolkit
6+
37
## Problem
48

5-
Users need a way to stay informed about current events through a concise and easily accessible news headlines feed. Existing solutions might be cluttered, overwhelming, or lack personalization options.
9+
Existing news apps for end-users can be cluttered, overwhelming, or lack personalization options. For developers, building a fully-featured news app from scratch is time-consuming and requires significant effort, especially when including a backend.
610

711
## Solution
812

9-
This Flutter application aims to provide a streamlined and user-friendly experience for browsing news headlines. It leverages a clean UI, efficient data handling, and a layered architecture to deliver relevant information quickly and ensure maintainability, scalability, and testability.
13+
Headlines Toolkit is a source-available Flutter application. Developers can freely view and evaluate the source code and run the app locally for a trial period of up to 32 consecutive days. Any use beyond this trial period, including continued local use, modification, production use, or distribution, requires a commercial license. It provides a streamlined and user-friendly experience for browsing news headlines and is designed as a comprehensive, full-stack solution, saving developers time and effort in building their own news apps. The app leverages a clean UI, efficient data handling, and a layered architecture to deliver relevant information quickly. It currently uses a Firebase backend, with plans to add Supabase support in the future.
14+
15+
## Target Audience
16+
17+
Developers seeking a ready-made, customizable foundation for building their own news applications.
18+
19+
## Business Model
20+
21+
Commercial licenses are offered to developers, granting them the rights to use the Headlines Toolkit source code beyond the 32-day evaluation period, including for production use, customization, and distribution of derived applications. The source code is freely available for a 32-day evaluation, allowing developers to thoroughly test the software before purchasing a commercial license.
22+
23+
## App Features
24+
25+
- **Headlines Feed:** Displays a minimalist list of news headlines, showing only the title, with source, category, and country represented as icons.
26+
- **Headline Details Page:** When a user taps a headline, they are taken to a details page that displays:
27+
- Title
28+
- Image
29+
- Source
30+
- Category
31+
- Date
32+
- "Continue Reading" button (opens the original source URL in the user's default browser)
33+
- **Search:** Allows users to search for specific headlines.
34+
- **Filtering:** Allows users to filter headlines by category, source, and event country.
35+
- **User Accounts/Profiles:** Functionality for user authentication and profile management.
36+
- **Personalized Recommendations:** Provides personalized news recommendations based on user preferences and activity.
37+
- **Saving Articles:** Allows users to save articles for later reading.
38+
- **Offline Reading:** Allows users to access saved articles even without an internet connection.
39+
- **Push Notifications:** Sends push notifications to users about breaking news or important updates.
40+
- **News Categories/Topics:** Provides a wide range of news categories and topics beyond basic filtering.
41+
- **Social Sharing:** Allows users to share articles on social media platforms.
42+
- **Comments/Discussion Features:** Provides a platform for users to comment on and discuss articles.
43+
- **Dark Mode:** Offers a dark mode option for improved readability in low-light conditions.
1044

1145
## User Experience Goals
1246

13-
- **Clarity:** Headlines should be presented in a clear and readable format.
47+
- **Clarity:** Headlines and content should be presented in a clear and readable format.
1448
- **Efficiency:** The app should load quickly and respond smoothly to user interactions.
1549
- **Simplicity:** The interface should be intuitive and easy to navigate.
16-
- **Potentially:** Offer filtering or customization options to tailor the feed to user preferences.
1750

1851
## How it Should Work
1952

20-
1. The app fetches headlines from a data source (likely an API, based on the use of `HtInMemoryHeadlinesClient` and `HtHeadlinesRepository`).
21-
2. Headlines are displayed in a list or similar format.
22-
3. Users can potentially interact with headlines (e.g., tap to view full articles, though this is not yet confirmed by the provided code).
23-
4. The app offer filtering options to refine the displayed headlines.
24-
5. The app offers a search functionality to find specific headlines.
53+
1. The app fetches headlines from a data source (currently Firebase, with plans for Supabase).
54+
2. Headlines are displayed in a minimalist list in the feed.
55+
3. Users can tap on a headline to view the details page.
56+
4. Users can search and filter headlines.
57+
5. The app will support various features common to top news apps, as listed above.

‎memory-bank/progress.md

Lines changed: 28 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,33 +3,48 @@
33
## What Works
44

55
- Multiple environment configurations (development, staging, production) using `main_*.dart` files.
6-
- BLoC pattern implementation for state management.
7-
- Repository pattern for data access.
6+
- BLoC pattern implementation for state management:
7+
- `AppBloc` for app-level state (navigation and theme).
8+
- `HeadlinesFeedBloc` for managing headlines data, filtering, and fetching/refreshing.
9+
- `HeadlinesSearchBloc` for managing headlines search.
10+
- Repository pattern for data access (`HtHeadlinesRepository`).
811
- Initial Memory Bank setup.
9-
- Router refactoring with named navigation and example sub-route.
12+
- Routing using `go_router`:
13+
- Routes for headlines feed, search, and account.
14+
- Nested route for article details within the headlines feed.
1015
- `headlines-feed` feature:
1116
- `HeadlinesFeedBloc` for managing headlines data and filtering.
1217
- `HeadlinesFeedPage` and `_HeadlinesFeedView` for displaying headlines.
13-
- `_HeadlinesFilterBottomSheet` for applying filters.
14-
- Infinite scroll functionality.
15-
- Refresh functionality.
18+
- Filtering by category, source, and event country.
19+
- Infinite scroll functionality.
20+
- Refresh functionality.
1621
- `headlines-search` feature:
1722
- `HeadlinesSearchBloc` for managing headlines search.
1823
- `HeadlinesSearchPage` and `HeadlinesSearchView` for displaying search results.
19-
- Routing for the search feature.
24+
- Debounced search term input.
25+
- Error handling within BLoCs, with specific error states.
26+
- Page/View pattern for UI components.
2027

2128
## What's Left to Build
2229

23-
- Integration with a real headlines API (currently using an in-memory client).
24-
- Full implementation of filtering functionality (UI is present, but API integration may be needed).
25-
- Navigation and routing (basic setup exists, named navigation implemented, sub-routes need further implementation based on application needs).
26-
- Error handling and potentially loading states (basic widgets exist, but more robust handling may be needed).
30+
- Integration with the Firebase backend (currently using an in-memory client).
31+
- Implementation of remaining features:
32+
- User accounts/profiles.
33+
- Personalized recommendations.
34+
- Saving articles.
35+
- Offline reading.
36+
- Push notifications.
37+
- News categories/topics (beyond basic filtering).
38+
- Social sharing.
39+
- Comments/discussion features.
40+
- Full implementation of the article details page (currently a placeholder).
2741
- Testing.
42+
- Future integration with Supabase.
2843

2944
## Current Status
3045

31-
- Early development stage. Core architecture and the main `headlines-feed` and `headlines-search` features have basic implementations, but many features and refinements are still needed. The memory bank has been updated with information about the layered architecture, barrel files, the convention to document no-op operations, and error handling best practices.
46+
- Early development stage. Core architecture, basic headline feed and search functionality, and initial memory bank documentation are complete. The focus is now on creating the README and then implementing the remaining features and backend integration.
3247

3348
## Known Issues
3449

35-
- None identified yet, based on the limited code provided.
50+
- None identified yet.

‎memory-bank/projectbrief.md

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,27 @@
22

33
## Overview
44

5-
This project is a Flutter application, likely a news headlines app, based on the directory structure and file names (e.g., `headlines-feed`). It utilizes the BLoC pattern for state management and has different entry points for development, staging, and production environments.
5+
This project, **Headlines Toolkit**, is a source-available Flutter application designed to provide a foundation for building news apps. It utilizes the BLoC pattern for state management and has different entry points for development, staging, and production environments.
66

77
## Goals
88

99
- Provide a functional and user-friendly application for displaying news headlines.
10-
- Implement a clean and maintainable architecture using Flutter and BLoC. The project uses a layered architecture as described in `memory-bank/systemPatterns.md`.
10+
- Implement a clean and maintainable architecture using Flutter and BLoC.
1111
- Support multiple environments (development, staging, production).
1212

13-
## Key Features (Inferred)
13+
## Key Features
1414

15-
- Displaying a feed of headlines.
16-
- Searching headlines.
17-
- Potentially filtering headlines (based on `headline_filter.dart`).
18-
- Navigation between different screens/sections (based on `router/`).
15+
- Headlines Feed (title-only, with source/category/country icons).
16+
- Headline Details Page (title, image, source, category, date, "Continue Reading" button).
17+
- Search.
18+
- Filtering (by category, source, and event country).
19+
- User accounts/profiles.
20+
- Personalized recommendations.
21+
- Saving articles.
22+
- Offline reading.
23+
- Push notifications.
24+
- News categories/topics.
25+
- Social sharing.
26+
- Comments/discussion features.
27+
- Dark Mode.
28+
- Navigation between different screens/sections.

‎memory-bank/techContext.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,14 @@
88
- **Dependency Injection:** Manual
99
- **Routing:** GoRouter (for declarative routing and navigation)
1010

11+
## Backend
12+
13+
- **Current:** Firebase
14+
- **Future:** Supabase
15+
1116
## Development Setup
1217

18+
- The project is a full-stack application with a Flutter frontend and a Firebase backend.
1319
- The project uses flavor-specific entry points (`main_development.dart`, `main_staging.dart`, `main_production.dart`).
1420
- Dependencies are managed using `pubspec.yaml`.
1521

‎pubspec.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
name: ht_main
22
description: main headlines toolkit mobile app.
3-
version: 0.15.0
3+
version: 0.15.1
44
publish_to: none
55
repository: https://github.com/headlines-toolkit/ht-main
66
environment:

0 commit comments

Comments
 (0)