The Looker Content Platform Development

Expert development assistant for The Looker website - a sub-brand of The Daily Beast built with Astro SSR and Cloudflare Workers.

Project Context

You are working on "The Looker" website that will live at `thelooker.thedailybeast.com`. This is built with Astro SSR, deployed to Cloudflare Workers, and designed to eventually scale to power the entire Daily Beast website.

Development Commands

Always use these commands for development tasks:

Tech Stack

API Integration Guidelines

The app connects to a content cache API that provides Daily Beast content. Full API documentation is in `documentation/middleware-api.json` (OpenAPI spec).

Core Endpoints

When working with content, use these endpoints:

Query Parameters

Optimize API calls with these parameters:

Environment Variables

Ensure these are configured in `.env` (see `.env.example`):

Component Architecture

Follow this strict component organization:

```

src/

components/

blocks/ # Article content blocks (reusable)

TextBlock.astro

ImageBlock.astro

HeaderBlock.astro

QuoteBlock.astro

ListBlock.astro

ReferenceBlock.astro

OEmbedBlock.astro

CustomEmbedBlock.astro

RawHtmlBlock.astro

layout/ # Site structure

Header.astro # The Looker branded header

Footer.astro # The Looker branded footer

Navigation.astro

ui/ # Shadcn components

features/ # Page-specific components

ArticleLayout.astro

HomepageGrid.astro

TagPageList.astro

```

Content Block Types

Articles from the API contain `content_elements` arrays. Handle these block types:

Text & Structure

Media

References

Path Aliases

Use these TypeScript path aliases (configured in `tsconfig.json` and `components.json`):

Styling Approach

Follow these styling guidelines:

Critical Development Guidelines

**ALWAYS follow these rules:**

1. **Ask Questions First** - Don't assume anything before making big decisions. Always ask the user for clarification.

2. **Test Thoroughly** - Test all changes across different screen sizes and content types.

3. **Commit Properly** - Always create proper git commits with clear messages and take notes.

4. **Maintain AI Decision Log** - Keep an AI decision log of all architectural choices.

5. **Update TASKS.md** - Constantly update the `@TASKS.md` file with current progress and next steps.

6. **Use Out-of-the-Box Components** - Do NOT build anything from scratch without user approval. Use Shadcn UI components and existing patterns.

7. **Component Flexibility** - Build components to support both The Looker and future Daily Beast branding.

8. **Error Handling** - Handle missing data gracefully - all fields should have defaults.

9. **TypeScript** - Use TypeScript for type safety throughout the project.

10. **Mobile-First** - Always design for mobile first, then enhance for desktop.

Sample Data

Reference these sample JSON files in `documentation/` for development:

Third-Party Integrations

Zephr API (User Authentication)

Shadcn UI

Planned Integrations

Workflow

When working on tasks:

1. Read the task requirements carefully from `@TASKS.md`

2. Ask clarifying questions before making architectural decisions

3. Use existing Shadcn UI components - don't build from scratch

4. Follow the component architecture strictly

5. Handle all edge cases and missing data gracefully

6. Test on mobile and desktop viewports

7. Update `@TASKS.md` with progress

8. Log important decisions in the AI decision log

9. Commit changes with clear, descriptive messages

Example Usage

When asked to create a new article layout component:

1. Check `article-with-all-elements.json` for the complete data structure

2. Confirm requirements and ask about any missing specifications

3. Use existing block components from `components/blocks/`

4. Build the layout in `components/features/ArticleLayout.astro`

5. Ensure mobile-first responsive design

6. Handle all content_elements types with proper fallbacks

7. Test with sample data

8. Update `@TASKS.md` with completion status

9. Commit with message like "feat: add ArticleLayout component with full block support"