12-08-2025

🚀 Major Refactor for Maintainability & Robustness

This release marks a significant architectural overhaul of the API's core data routes. The primary focus was not on adding new features, but on a deep refactoring effort to improve maintainability, extensibility, and resilience. We've centralized logic, streamlined middleware, and enhanced data model consistency.

---

🏛️ Architectural Refactor: Middleware & Data Operations

We've fundamentally changed how the API handles data requests to make the system cleaner and much easier to extend in the future. The big-picture goal was to move logic out of individual route handlers and into single-responsibility components.

Our Rationale: Large switch statements and duplicated logic in every route handler are hard to maintain. By centralizing data operations and middleware responsibilities, we can add new data models or change behavior in one place, rather than many.

• New DataOperationRegistry: This is the centerpiece of the refactor. A new registry now centrally manages all CRUD (Create, Read, Update, Delete) operations, completely eliminating the large, cumbersome switch statements from our route handlers.
• Smarter Middleware Chain:
  • A new DataFetchMiddleware is now solely responsible for fetching items by ID, making the data available to other middleware in the request context.
  • The OwnershipCheckMiddleware has been simplified. It no longer fetches data itself; it now just validates ownership on the pre-fetched item.
• Optimized Database Calls: By passing fetched data through the request context, we've eliminated redundant database reads that were occurring in the old workflow.

🛡️ Enhanced Error Handling & Resilience

We've hardened the API to be more resilient against malformed requests, ensuring it provides clear and actionable feedback instead of generic server errors.

• Robust Query Parameter Parsing: Added try-catch blocks around the parsing of filter and sort query parameters. Invalid JSON or incorrect formats now return a specific BadRequestException.
• Safe Request Body Handling: The logic that converts incoming JSON to data models in POST requests is now wrapped in a try-catch block, gracefully handling malformed bodies.
• Improved Logging: Implemented more comprehensive logging throughout the data routes, including error and stack trace details, to improve visibility for debugging.

🔄 Data Model & Synchronization Updates

To keep the API in sync with changes across the entire toolkit, we've updated several data models and permissions.

• Data Model Consistency:
  • The feedActionStatus field has been renamed to feedDecoratorStatus to align with terminology used in the client applications.
  • A user's language preference is no longer a simple string ('en') but a structured Language object, improving data integrity.
• Secure Guest User Updates: Guest users are now permitted to update a secure, whitelisted portion of their own user object (specifically, their feedDecoratorStatus), which is essential for certain client-side features. This is handled with a secure partial update that prevents any changes to sensitive fields.

03-08-2025

🚀 Enhanced Security, Admin Control & Data Refactoring

This release brings foundational improvements to the API, focusing on security, system stability, and a significant refactoring of how data is seeded and managed. These changes make the API more robust, secure, and easier to manage from an administrative perspective.

---

🛡️ Security & Stability Enhancements

We've introduced two major features to protect the API from abuse and ensure stable operation.

• API Rate Limiting: A new, configurable rate-limiting system has been implemented to prevent abuse of key endpoints.

  • It is applied to the authentication endpoint (/auth/request-code) based on IP address and to the data API (/api/v1/data) based on the authenticated user's ID.
  • Limits and time windows are easily configurable via new environment variables.
  • A rate_limiting.bypass permission is granted to Admin and Publisher roles, ensuring administrative tasks are not affected.
  • The system now correctly returns an HTTP 429 (Too Many Requests) status code when a limit is exceeded.

• Declarative Admin Account Management: We've introduced a more robust way to manage the system's administrator account.

  • A new OVERRIDE_ADMIN_EMAIL environment variable allows you to securely define the sole administrator.
  • On startup, the database seeding process will automatically create or update the admin user based on this variable, simplifying initial setup and account recovery.

💾 Database Seeding & Data Model Refactor

The database seeding process has been significantly refactored. The goal was to separate foundational system data from dynamic content fixtures, making the initial setup cleaner and more predictable.

Our Rationale: The core database seed should only be responsible for setting up the essential, static data required for the application to function—not for populating it with sample content like headlines or topics.

• Leaner Seeding Process: The default seeding operation no longer populates the database with content fixtures. Its primary responsibilities are now reduced to creating database indexes and seeding the override admin user.
• New Language Entity: A new Language data model has been introduced as a first-class entity within the API, complete with its own repository and role-based access permissions.
• Read-Only Static Data: The Country and newly added Language models are now configured as read-only through the API. This enforces the new philosophy that this type of foundational data is managed via the database seeding process, not through user-driven API calls.

23-07-2025

🚀 Project-Wide Renaming & Standardization

This release marks a significant foundational refactoring focused on renaming the core project and all internal dependencies. The primary goal is to align with the new 'Flutter News App Toolkit' ecosystem and establish a more conventional, maintainable, and descriptive codebase.

This is a breaking, comprehensive change that updates nearly every file to use the new naming conventions, from package imports to type definitions.

✨ Renaming & Rebranding Initiative

• Project Rebranded: The core project has been officially rebranded from 'Headlines Toolkit' to 'Flutter News App Toolkit'. The API repository itself is now named flutter_news_app_api_server_full_source_code.
• Internal Packages Renamed: All internal private dependencies, previously prefixed with ht_ (e.g., ht_data_client, ht_shared), have been renamed to remove the prefix (e.g., data_client, core).
• Documentation & Metadata Updated: The README.md and pubspec.yaml have been updated to reflect the new project name, description, and repository URLs.

🔧 Codebase & Standardization

• Codebase Adapted: All import statements and type annotations have been updated across the entire codebase to use the new package names (e.g., HtDataRepository is now DataRepository).
• Standardized Error Handling: The custom HtHttpException has been replaced with the more standard HttpException type for consistent error handling across the application.

🔧 Configuration & Tooling Updates

• Configuration Aligned: The .env.example file has been updated with the new database name to match the new branding.
• Dependabot Updated: The dependabot.yaml configuration has been updated to correctly ignore the newly named private dependencies.
• Dev Dependency Upgrade: The very_good_analysis dev dependency has been upgraded to its latest version.

21-07-2025

✨ SendGrid Integration & Configuration Refinements

This release marks a significant upgrade to our email capabilities by migrating from an in-memory solution to SendGrid for sending real transactional emails. To support this major feature, we have also refactored our application configuration and environment variable handling to be more robust, maintainable, and secure.

✨ Transactional Email via SendGrid

• Email Service Migration: The API's email service has been migrated to use SendGrid, enabling the application to send real transactional emails, such as One-Time Passwords (OTPs), for the first time.
• New Environment Configuration: New environment variables (SENDGRID_API_KEY, DEFAULT_SENDER_EMAIL, OTP_TEMPLATE_ID) have been introduced to configure the SendGrid integration. The .env.example and documentation have been updated accordingly.
• Auth Service Integration: The AuthService has been updated to use the new email service, passing the configured sender email and template ID for sending OTPs.

🔧 Configuration & Code Quality Improvements

• Robust Environment Variable Handling: A new helper method now centralizes the logic for retrieving required environment variables. This reduces boilerplate code and ensures the application fails fast if a critical variable is missing.
• Refined API Client Setup: The SendGrid API client initialization has been improved by separating the base URL from the version path, making the configuration clearer and more flexible.
• Code Cleanup: General code cleanup was performed across several files, including removing obsolete in-memory email code and applying formatting adjustments for better readability.

20-07-2025

🚀 Authentication Overhaul & Production-Ready Enhancements

This release delivers a comprehensive overhaul of the API's authentication system and backend infrastructure. The primary focus has been on creating a seamless and secure experience for guest users converting to permanent accounts.

Simultaneously, we've executed a major push to harden the entire platform for production by migrating critical authentication data to a persistent store, externalizing sensitive configurations, and implementing performance-boosting database indexes.

✨ Seamless & Secure Guest User Conversion

The entire lifecycle for guest users has been re-architected to be more intelligent, secure, and streamlined.

• Intelligent Sign-In Flow: The authentication process now smartly handles guest users. If a guest signs in with a new email, their account is seamlessly converted to a permanent one. If they use an email that already exists, they are logged into the existing permanent account, and their old guest data is securely cleaned up.
• Simplified API: The dedicated /link-email endpoints have been removed. All guest conversion logic is now consolidated directly into the main sign-in flow, creating a simpler and more robust API surface.
• Automated Token Invalidation & Cleanup: When a guest converts or signs into an existing account, their old guest token is automatically invalidated and their temporary guest account is deleted, preventing orphaned data and improving security.
• Reliable User Data Provisioning: A centralized helper now ensures that all necessary user documents (like settings and preferences) are idempotently created for any new user, whether they register directly or are converted from a guest account.

🛡️ Production-Ready Security & Persistence

We've moved beyond in-memory solutions and hardcoded secrets to a more robust and secure architecture.

• Persistent Authentication Data: Token blacklists and active verification codes are no longer stored in-memory. They are now persisted in dedicated MongoDB collections, ensuring they survive server restarts.
• Automated Data Cleanup with TTL Indexes: We've implemented MongoDB's Time-To-Live (TTL) indexes on the new authentication collections. This automates the cleanup of expired tokens and verification codes directly within the database, ensuring excellent data hygiene with no manual intervention.
• Externalized JWT Configuration: All sensitive JWT secrets, issuer URLs, and token expiry settings are now loaded from environment variables instead of being hardcoded, following security best practices.
• Structured Logging: All print() statements have been replaced with a structured Logger, providing vastly improved observability for monitoring and debugging.

🚀 Performance & Backend Modernization

• Automated Text Search Indexing: The database seeding process now automatically creates text search indexes on headlines, topics, and sources. This significantly improves the performance and efficiency of search operations.
• Migration to MongoDB ObjectIDs: The application now uses MongoDB's native ObjectId for all unique identifier generation, replacing the generic uuid package. This aligns our ID strategy with our database technology.
• Standardized Timestamps: The API now automatically and consistently sets createdAt and updatedAt fields for all new and updated data, ensuring data integrity.

14-07-2025

🛡️ API Response & Error Handling Overhaul

This release delivers a comprehensive overhaul of our API's response handling, ensuring that client applications receive data and errors in a consistent, predictable, and secure manner. We have standardized the format for both successful responses and critical error messages, while also fixing a significant CORS issue that impacted error visibility.

✨ Key Enhancements

Critical Error Handling & CORS Fix

• Fixed Unreadable Error Messages: Resolved a critical issue where browser-based clients could not read API error messages due to CORS policies. Error responses now dynamically include the necessary Access-Control-Allow-Origin headers, ensuring clients can always access detailed error information.
• Centralized Error Generation: All JSON error responses are now generated by a single helper function, standardizing their format and ensuring consistent behavior across the API.
• New CORS Configuration: A new CORS_ALLOWED_ORIGIN environment variable has been introduced, allowing for explicit configuration of the allowed origin in production environments.

Standardized Success Responses

• New Response Helper: A ResponseHelper utility has been introduced to standardize the format of all successful API responses. This reduces boilerplate code in route handlers and ensures a consistent SuccessApiResponse structure across all endpoints.
• Widespread Refactoring: Numerous route handlers have been refactored to use the new helper, significantly cleaning up the codebase and improving maintainability.

🔧 Code Quality & Organization

• Improved Code Organization: The RequestId class has been moved to its own dedicated file for better modularity.
• Logging Cleanup: Redundant request ID prefixes have been removed from log statements, as this is now handled more cleanly through the request context.

13-07-2025

🛡️ Authentication System Hardening

This release delivers a focused set of critical security and stability enhancements to the API's authentication system, specifically targeting the dashboard login flow. We have refactored the authorization logic and implemented new security checks to create a more robust and secure login process.

Key Authentication Enhancements

• Critical Security Fix: Email Verification Check
  A new security check has been implemented during dashboard login code verification. This explicitly verifies that the email provided in the request matches the email associated with the found user, preventing a potential account access loophole.

• Enhanced Dashboard Authorization Logic
  Dashboard login access is now determined by a specific dashboard.login permission instead of a direct role check. The flow also includes a critical re-verification step during code validation to ensure permissions are checked at the exact moment of login.

• More Resilient API Request Parsing
  The /request-code endpoint has been improved to robustly handle the isDashboardLogin flag whether it is sent as a boolean (true) or a string ("true"), preventing potential client-side errors and improving API resilience.

• Improved Error Handling & Logging
  The authentication service now captures and logs full stack traces for unexpected exceptions, providing more comprehensive information for debugging. The internal validation logic has also been refactored for better clarity and maintainability.

12-07-2025

🚀 Architectural Revolution: Migration to MongoDB & Enhanced RBAC

This release represents a landmark architectural overhaul of the API. We have completed a full data store migration from PostgreSQL to MongoDB, embracing a more flexible document-oriented model to pave the way for future feature development.

In parallel, we have fundamentally refactored our core data models and rebuilt the user role system from the ground up. The new dual-role RBAC system (appRole and dashboardRole) provides more granular and secure access control, while model renames (Category -> Topic) align the API with our evolving domain language. These changes are supported by significant improvements in logging, configuration, and security enforcement.

✨ Key Architectural Changes

• Database Migration to MongoDB: The application's primary data store has been completely migrated from PostgreSQL to MongoDB. This involved a comprehensive update of the entire data access layer, repository implementations, and data seeding logic.
• Enhanced Dual-Role RBAC: The user role system has been overhauled. A user now has distinct appRole (for application features) and dashboardRole (for administrative functions), allowing for more precise and secure permission management across the entire platform.
• Core Model Refactoring: The Category model has been replaced by Topic, and AppConfig has been replaced by RemoteConfig. These changes are reflected across the database schema, repositories, and all related API endpoints.

🛡️ Security & API Enhancements

• Ownership Enforcement Middleware: A new middleware has been introduced to enforce data ownership on user-specific records (User, UserAppSettings, etc.). This ensures users can only access or modify their own data, unless they possess administrative privileges.
• Simplified API Querying: Collection endpoints (/api/v1/data) now accept a generic, JSON-encoded filter parameter for powerful, MongoDB-style queries. This replaces model-specific query parameters.
• Standardized Error Codes: HTTP error codes returned by the API are now standardized to camelCase for better consistency.

🔧 Technical Refinements & Performance

• Structured Logging: All print() statements have been replaced with a structured Logger, significantly improving system observability and making debugging more efficient.
• Optimized Dashboard Summary: The dashboard summary endpoint has been optimized to retrieve only document counts, drastically reducing data transfer and improving performance.
• Centralized Timestamp Handling: A new utility function now centralizes the conversion of DateTime objects to ISO 8601 strings, ensuring data consistency for all model deserialization.
• Robust Environment Loading: The .env file loading mechanism has been improved to be more resilient, making local development setup more reliable.

06-07-2025

🚀 Major Architectural Upgrade: PostgreSQL Database Integration

This release marks a fundamental shift in the application's architecture, migrating the entire data persistence layer from an in-memory solution to a robust PostgreSQL database. This crucial upgrade ensures data durability, provides scalability, and establishes a production-grade foundation for the API.

Alongside this migration, this release also includes a suite of critical fixes and refinements that stabilize the new data layer, improve dependency management, and harden the overall application configuration, ensuring the new system is reliable and robust from day one.

✨ Key Features & Architectural Changes

• PostgreSQL Data Persistence: The API no longer uses a temporary, in--memory store. All data is now persisted in a PostgreSQL database, managed via the DATABASE_URL environment variable. This is a foundational step towards a production-ready environment.
• Automated Database Setup & Seeding: A new DatabaseSeedingService has been introduced to automatically and idempotently create all necessary database tables and seed initial data on server startup. This drastically simplifies first-time setup and ensures database consistency across all environments.
• Centralized Dependency Management: The application's bootstrapping logic has been centralized. Core services and repositories are now managed and provided through a new AppDependencies singleton, ensuring consistent, efficient resource utilization and a cleaner middleware chain.

🔧 Stability Fixes & Core Refinements

• Robust Data Type Handling: Resolved critical data integrity issues by implementing explicit serialization and deserialization logic for complex data types like DateTime and JSONB when interacting with the PostgreSQL database.
• Enhanced Environment Configuration: Migrated to the dotenv package for loading environment variables, providing more robust configuration management and better error handling for missing variables.
• Refined CORS Behavior: The CORS middleware has been improved to dynamically handle localhost origins for development while enforcing a strict CORS_ALLOWED_ORIGIN for production, with added logging for easier debugging.
• Updated Database Schema: The database schemas and seeding logic for core entities have been updated to support richer data models and ensure correct data population.

05-07-2025

🛡️ Major Authentication & Role Management Overhaul

This release introduces a fundamental refactor of our API's security and user management model. We have transitioned from a single-role assignment to a flexible, multi-role architecture, enabling more granular and powerful access control.

Building on this, we've implemented a context-aware authentication flow that hardens security for the administrative dashboard. Instead of a sign-up process, dashboard access is now strictly limited to pre-existing users with privileged roles, preventing unauthorized access attempts at the earliest stage.

✨ Key Features & Enhancements

Enhanced Role-Based Access Control (RBAC)

• Multi-Role Architecture: The core system has been re-engineered to support multiple roles per user. A user can now simultaneously be a standardUser, a publisher, and more, allowing for precise permission management.
• Granular Permission Checks: The PermissionService now leverages the new multi-role system, checking a user's entire list of roles to determine access rights. A new publisher role with content creation permissions has also been introduced.
• JWT Claims Update: JSON Web Tokens (JWTs) issued by the API now include a complete list of a user's roles, providing client applications with all the necessary information for authorization.

Secure, Context-Aware Authentication

• Hardened Dashboard Login: The authentication flow is now context-aware. Login attempts to the dashboard (using an is_dashboard_login: true flag) now trigger a strict pre-validation check. This ensures the user's email is already registered and that they possess the required admin or publisher role before an authentication code is sent. This prevents unauthorized users from even initiating a login to the dashboard.
• Streamlined User Creation: Legacy logic for migrating anonymous guest accounts has been removed from the user creation process, simplifying the overall authentication service and making it more robust.

🔧 Developer Experience & Code Quality

• Admin User Seeding: To simplify local development and testing, the API now automatically seeds the user repository with a default [email protected] user on application startup.
• Refactored Auth Service: The AuthService has been refactored to centralize and de-duplicate user retrieval logic, improving code maintainability and reusability.
• Documentation Updates: The README.md has been updated to detail the new "Flexible Role-Based Access Control (RBAC)" and "Secure Authentication" features.