ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b2ad4b7e856621af5f953f10b38f296984d4f94d
BMAD-METHOD/demos/early-v3alpha-full-stack-app-demo/10-sharded-docs/epic-1.md

11 KiB
Raw Blame History

Epic 1: Project Initialization, Setup, and HN Content Acquisition

This document is a granulated shard from the main "BETA-V3/v3-demos/full-stack-app-demo/8-prd-po-updated.md" focusing on "Epic 1: Project Initialization, Setup, and HN Content Acquisition".

  • Goal: Establish the foundational project structure, including the Next.js application, Supabase integration, deployment pipeline, API/CLI triggers, core workflow orchestration, and implement functionality to retrieve, process, and store Hacker News posts/comments via a ContentAcquisitionFacade, providing data for newsletter generation. Implement the database event mechanism to trigger subsequent processing. Define core configuration tables, seed data, and set up testing frameworks.

  • Story 1.1: As a developer, I want to set up the Next.js project with Supabase integration, so that I have a functional foundation for building the application.

    • Acceptance Criteria:
      • The Next.js project is initialized using the Vercel/Supabase template.
      • Supabase is successfully integrated with the Next.js project.
      • The project codebase is initialized in a Git repository.
      • A basic project README.md is created in the root of the repository, including a project overview, links to main documentation (PRD, architecture), and essential developer setup/run commands.

  • Story 1.2: As a developer, I want to configure the deployment pipeline to Vercel with separate development and production environments, so that I can easily deploy and update the application.

    • Acceptance Criteria:
      • The project is successfully linked to a Vercel project with separate environments.
      • Automated deployments are configured for the main branch to the production environment.
      • Environment variables are set up for local development and Vercel deployments.

  • Story 1.3: As a developer, I want to implement the API and CLI trigger mechanisms, so that I can manually trigger the workflow during development and testing.

    • Acceptance Criteria:
      • A secure API endpoint is created.
      • The API endpoint requires authentication (API key).
      • The API endpoint (/api/system/trigger-workflow) creates an entry in the workflow_runs table and returns the jobId.
      • The API endpoint returns an appropriate response to indicate success or failure.
      • The API endpoint is secured via an API key.
      • A CLI command is created.
      • The CLI command invokes the /api/system/trigger-workflow endpoint or directly interacts with WorkflowTrackerService to start a new workflow run.
      • The CLI command provides informative output to the console.
      • All API requests and CLI command executions are logged, including timestamps and any relevant data.
      • All interactions with the API or CLI that initiate a workflow must record the workflow_run_id in logs.
      • The API and CLI interfaces adhere to mobile responsiveness and Tailwind/theming principles.

  • Story 1.4: As a system, I want to retrieve the top 30 Hacker News posts and associated comments daily using a configurable ContentAcquisitionFacade, so that the data is available for summarization and newsletter generation.

    • Acceptance Criteria:
      • A ContentAcquisitionFacade is implemented in supabase/functions/_shared/ to abstract interaction with the news data source (initially HN Algolia API).
      • The facade handles API authentication (if any), request formation, and response parsing for the specific news source.
      • The facade implements basic retry logic for transient errors.
      • Unit tests for the ContentAcquisitionFacade (mocking actual HTTP calls to the HN Algolia API) achieve >80% coverage.
      • The system retrieves the top 30 Hacker News posts daily via the ContentAcquisitionFacade.
      • The system retrieves associated comments for the top 30 posts via the ContentAcquisitionFacade.
      • Retrieved data (posts and comments) is stored in Supabase database, linked to the current workflow_run_id.
      • This functionality can be triggered via the API and CLI.
      • The system logs the start and completion of the retrieval process, including any errors.
      • Upon completion, the service updates the workflow_runs table with status and details (e.g., number of posts fetched) via WorkflowTrackerService.
      • Supabase migrations for hn_posts and hn_comments tables (as defined in architecture.txt) are created and applied before data operations.

  • Story 1.5: Define and Implement workflow_runs Table and WorkflowTrackerService

    • Goal: Implement the core workflow orchestration mechanism (tracking part).
    • Acceptance Criteria:
      • Supabase migration created for the workflow_runs table as defined in the architecture document.
      • WorkflowTrackerService implemented in supabase/functions/_shared/ with methods for initiating, updating step details, incrementing counters, failing, and completing workflow runs.
      • Service includes robust error handling and logging via Pino.
      • Unit tests for WorkflowTrackerService achieve >80% coverage.

  • Story 1.6: Implement CheckWorkflowCompletionService (Supabase Cron Function)

    • Goal: Implement the core workflow orchestration mechanism (progression part).
    • Acceptance Criteria:
      • Supabase Function check-workflow-completion-service created.
      • Function queries workflow_runs and related tables to determine if a workflow run is ready to progress to the next major stage.
      • Function correctly updates workflow_runs.status and invokes the next appropriate service function.
      • Logic for handling podcast link availability is implemented here or in conjunction with NewsletterGenerationService.
      • The function is configurable to be run periodically.
      • Comprehensive logging implemented using Pino.
      • Unit tests achieve >80% coverage.

  • Story 1.7: Implement Workflow Status API Endpoint (/api/system/workflow-status/{jobId})

    • Goal: Allow developers/admins to check the status of a workflow run.
    • Acceptance Criteria:
      • Next.js API Route Handler created at /api/system/workflow-status/{jobId}.
      • Endpoint secured with API Key authentication.
      • Retrieves and returns status details from the workflow_runs table.
      • Handles cases where jobId is not found (404).
      • Unit and integration tests for the API endpoint.

  • Story 1.8: Create and document docs/environment-vars.md and set up .env.example

    • Goal: Ensure environment variables are properly documented and managed.
    • Acceptance Criteria:
      • A docs/environment-vars.md file is created.
      • An .env.example file is created.
      • Sensitive information in examples is masked.
      • For each third-party service requiring credentials, docs/environment-vars.md includes:
        • A brief note or link guiding the user on where to typically sign up for the service and obtain the necessary API key or credential.
        • A recommendation for the user to check the service's current free/low-tier API rate limits against expected MVP usage.
        • A note that usage beyond free tier limits for commercial services (like Play.ht, remote LLMs, or email providers) may incur costs, and the user should review the provider's pricing.

  • Story 1.9 (New): Implement Database Event/Webhook: hn_posts Insert to Article Scraping Service

    • Goal: To ensure that the successful insertion of a new Hacker News post into the hn_posts table automatically triggers the ArticleScrapingService.
    • Acceptance Criteria:
      • A Supabase database trigger or webhook mechanism (e.g., using pg_net or native triggers calling a function) is implemented on the hn_posts table for INSERT operations.
      • The trigger successfully invokes the ArticleScrapingService (Supabase Function).
      • The invocation passes necessary parameters like hn_post_id and workflow_run_id to the ArticleScrapingService.
      • The mechanism is robust and includes error handling/logging for the trigger/webhook itself.
      • Unit/integration tests are created to verify the trigger fires correctly and the service is invoked with correct parameters.

  • Story 1.10 (New): Define and Implement Core Configuration Tables

    • Goal: To establish the database tables necessary for storing core application configurations like summarization prompts, newsletter templates, and subscriber lists.
    • Acceptance Criteria:
      • A Supabase migration is created and applied to define the summarization_prompts table schema as specified in architecture.txt.
      • A Supabase migration is created and applied to define the newsletter_templates table schema as specified in architecture.txt.
      • A Supabase migration is created and applied to define the subscribers table schema as specified in architecture.txt.
      • These tables are ready for data population (e.g., via seeding or manual entry for MVP).

  • Story 1.11 (New): Create Seed Data for Initial Configuration

    • Goal: To populate the database with initial configuration data (prompts, templates, test subscribers) necessary for development and testing of MVP features.
    • Acceptance Criteria:
      • A supabase/seed.sql file (or an equivalent, documented seeding mechanism) is created.
      • The seed mechanism populates the summarization_prompts table with at least one default article prompt and one default comment prompt.
      • The seed mechanism populates the newsletter_templates table with at least one default newsletter template (HTML format for MVP).
      • The seed mechanism populates the subscribers table with a small list of 1-3 test email addresses for MVP delivery testing.
      • Instructions on how to apply the seed data to a local or development Supabase instance are documented (e.g., in the project README.md).

  • Story 1.12 (New): Set up and Configure Project Testing Frameworks

    • Goal: To ensure that the primary testing frameworks (Jest, React Testing Library, Playwright) are installed and configured early in the project lifecycle, enabling test-driven development practices and adherence to the testing strategy.
    • Acceptance Criteria:
      • Jest and React Testing Library (RTL) are installed as project dependencies.
      • Jest and RTL are configured for unit and integration testing of Next.js components and JavaScript/TypeScript code (e.g., jest.config.js is set up, necessary Babel/TS transformations are in place).
      • A sample unit test (e.g., for a simple component or utility function) is created and runs successfully using the Jest/RTL setup.
      • Playwright is installed as a project dependency.
      • Playwright is configured for end-to-end testing (e.g., playwright.config.ts is set up, browser configurations are defined).
      • A sample E2E test (e.g., navigating to the application's homepage on the local development server) is created and runs successfully using Playwright.
      • Scripts to execute tests (e.g., unit tests, E2E tests) are added to package.json.