docs: add Phase 2 (Ingest Layer) documentation

[w7-mgfcode]

Summary

• Update README.md with API Endpoints section including ingest examples
• Mark Phase 2 as completed in PHASE-index.md
• Add comprehensive Phase 2 documentation (2-INGEST_LAYER.md)

Changes

• README.md: Added API Endpoints section with POST /ingest/sales-daily example
• docs/PHASE-index.md: Updated phase status table and added Phase 2 completion entry
• docs/PHASE/2-INGEST_LAYER.md: New comprehensive documentation for the ingest layer

Test plan

• Documentation renders correctly in markdown
• Links are valid
• Examples match implemented API

🤖 Generated with Claude Code

Summary by Sourcery

Document completion of Phase 2 (Ingest Layer) and introduce public API details for the sales ingestion endpoint.

Documentation:

• Add a dedicated Phase 2 ingest layer document describing the sales batch upsert API, validation, error handling, logging, and design decisions.
• Update the phase index to mark Phase 2 as completed, link to its documentation, and record its completion in the timeline.
• Extend the README with a high-level API Endpoints section, including the POST /ingest/sales-daily ingest example and feature overview.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sourcery-ai]

Reviewer's Guide

Documents completion of Phase 2 (Ingest Layer) by adding a new detailed phase document, updating the phase index to mark the ingest layer as complete and describe its API behavior, and enhancing the top-level README with API endpoint documentation and examples for the POST /ingest/sales-daily ingest endpoint.

Sequence diagram for POST /ingest/sales-daily request processing

sequenceDiagram
    actor Client
    participant ApiServer as FastAPI_app
    participant IngestRouter as ingest_routes
    participant IngestService as ingest_service
    participant KeyResolver as KeyResolver
    participant DB as PostgreSQL

    Client->>ApiServer: POST /ingest/sales-daily
    ApiServer->>IngestRouter: validate SalesDailyIngestRequest
    IngestRouter->>IngestService: upsert_sales_daily_batch(records)
    IngestService->>KeyResolver: resolve_store_codes(codes)
    KeyResolver->>DB: SELECT code,id FROM store WHERE code IN codes
    DB-->>KeyResolver: store_code -> store_id map
    KeyResolver-->>IngestService: store_code_to_id

    IngestService->>KeyResolver: resolve_skus(skus)
    KeyResolver->>DB: SELECT sku,id FROM product WHERE sku IN skus
    DB-->>KeyResolver: sku -> product_id map
    KeyResolver-->>IngestService: sku_to_product_id

    IngestService->>KeyResolver: resolve_dates(dates)
    KeyResolver->>DB: SELECT date FROM calendar WHERE date IN dates
    DB-->>KeyResolver: existing_dates
    KeyResolver-->>IngestService: valid_dates

    IngestService->>IngestService: validate rows, collect errors
    IngestService->>DB: INSERT ... ON CONFLICT DO UPDATE (valid_rows)
    DB-->>IngestService: upsert completed

    IngestService-->>IngestRouter: SalesDailyIngestResponse
    IngestRouter-->>ApiServer: JSON response
    ApiServer-->>Client: processed_count, rejected_count, errors, duration_ms

Loading

Entity relationship diagram for SalesDaily ingest grain and key resolution

erDiagram
    STORE {
        int id PK
        string code UK
        string name
    }
    PRODUCT {
        int id PK
        string sku UK
        string name
    }
    CALENDAR {
        date date PK
        int year
        int month
        int day
    }
    SALES_DAILY {
        int id PK
        date date FK
        int store_id FK
        int product_id FK
        int quantity
        decimal unit_price
        decimal total_amount
        datetime created_at
        datetime updated_at
        string unique_date_store_product_uk_date_store_id_product_id
    }

    STORE ||--o{ SALES_DAILY : has
    PRODUCT ||--o{ SALES_DAILY : has
    CALENDAR ||--o{ SALES_DAILY : provides_date

Loading

Class diagram for ingest layer schemas and service components

classDiagram
    class SalesDailyIngestRow {
        date date_type
        store_code str
        sku str
        quantity int
        unit_price Decimal
        total_amount Decimal
    }

    class SalesDailyIngestRequest {
        records list~SalesDailyIngestRow~
    }

    class IngestRowError {
        row_index int
        store_code str
        sku str
        date date_type
        error_code str
        error_message str
    }

    class SalesDailyIngestResponse {
        processed_count int
        rejected_count int
        total_received int
        errors list~IngestRowError~
        duration_ms float
    }

    class KeyResolver {
        +resolve_store_codes(db, codes) dict~str,int~
        +resolve_skus(db, skus) dict~str,int~
        +resolve_dates(db, dates) set~date_type~
    }

    class UpsertResult {
        processed_count int
        rejected_count int
        total_received int
        errors list~IngestRowError~
        duration_ms float
    }

    class IngestService {
        +upsert_sales_daily_batch(db, records, key_resolver) UpsertResult
    }

    SalesDailyIngestRequest "1" o-- "many" SalesDailyIngestRow : contains
    SalesDailyIngestResponse "1" o-- "many" IngestRowError : aggregates
    IngestService ..> KeyResolver : uses
    IngestService ..> SalesDailyIngestRow : processes
    IngestService ..> UpsertResult : returns
    SalesDailyIngestResponse <.. UpsertResult : compatible

Loading

File-Level Changes

Change	Details	Files
Mark Phase 2 (Ingest Layer) as completed and document its deliverables and behavior in the phase index.	Update phase status table to mark Phase 2 as Completed and link to the new ingest layer phase document Add a Phase 2 completion summary section including endpoint behavior, key deliverables, error codes, and response schema Remove the old Pending description for Phase 2 from the Pending Phases section Append a new timeline entry noting Phase 2 completion with the POST /ingest/sales-daily endpoint	docs/PHASE-index.md
Extend the README with ingest feature placement in the project layout and document the new ingest API endpoint with examples and feature notes.	Update the features directory tree to include the ingest module alongside data_platform Update examples directory tree to include the new api examples folder Add an API Endpoints section with health check and ingest endpoint descriptions Provide a curl example for POST /ingest/sales-daily including a minimal request body List key ingest endpoint features such as natural key resolution, idempotent upserts, partial success handling, and error codes, and link to the HTTP example file	README.md
Introduce a comprehensive Phase 2 ingest layer design and implementation document describing the POST /ingest/sales-daily endpoint, service layer, schemas, configuration, logging, and design decisions.	Describe Phase 2 objectives, design principles, and executive summary for the ingest layer Document the POST /ingest/sales-daily API contract including request/response schemas, validation rules, and error codes Detail Pydantic schemas, service-layer key resolution and upsert patterns, and PostgreSQL ON CONFLICT usage Document ingest-related configuration settings, logging events, directory structure, and example flows (happy path, idempotent replay, partial success) Capture key design decisions, integration points with existing tables and routes, next-phase implications, lessons learned, and references	docs/PHASE/2-INGEST_LAYER.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}