pavankumarkr2000/instagram-stories

1. Repository shape

This is a small Next.js + TypeScript frontend focused on an Instagram Stories-style viewer. The app is split into a page shell under app/, reusable UI pieces in components/, and static story content in data/.

2. App Router shell

The app/ directory defines the Next.js App Router entry points:

- app/layout.tsx provides the global HTML/app shell.

- app/page.tsx is the main screen that assembles the stories experience.

- app/globals.css and Tailwind-based styling establish the visual system.

3. Static content source

Story content appears to be local and compile-time defined in data/stories.ts.

This means the app is not architected around a backend API or CMS; the main data flow is:

static story dataset → list UI → modal viewer.

4. Main UI composition

The UI is decomposed into three core components:

- components/StoriesList.tsx for browsing available stories

- components/StoriesModal.tsx for the full-screen story viewer

- components/Progressbar.tsx for per-story progress feedback

5. List-to-modal interaction

StoriesList is the entry point for user selection. The likely interaction boundary is:

- user selects a story from the list

- selected story state is lifted to the page or modal controller

- StoriesModal opens with the chosen story and handles navigation within the sequence

6. Story playback model

The README describes the viewer behavior clearly: stories auto-advance every 5 seconds, while also supporting manual previous/next navigation and close/dismiss.

That implies the modal owns a timed playback state plus index-based navigation over the story array.

7. Progress indication subsystem

Progressbar.tsx is a dedicated presentation component for the story timer/progress UI. It likely reflects:

- current story index

- elapsed time within the active story

- completion state across the sequence

This is a separate visual concern from navigation, which helps keep the modal logic and rendering distinct.

8. Modal and animation boundary

react-modal is used for the overlay/dialog layer, making the story viewer a distinct interaction boundary from the rest of the page.

GSAP is used for animation, likely to animate transitions between stories and/or modal entrance/exit, rather than relying only on CSS transitions.

9. Styling stack

Tailwind CSS is the primary styling approach, with app/globals.css providing shared global rules. This suggests the UI is mostly utility-driven and component-scoped, with minimal custom styling infrastructure beyond the global stylesheet.

10. Runtime and build tooling

The stack is standard modern frontend tooling:

- Next.js for routing, rendering, and app structure

- TypeScript for typed component/data contracts

- Bun lockfile (bun.lock) indicating Bun is used as the package manager/runtime in the development workflow

- package.json, next.config.ts, and postcss.config.mjs support the app build pipeline

11. Data/control boundaries

The key architectural boundary is between:

- data: story metadata/content from data/stories.ts

- presentation: list/progress/modal components

- interaction/state: selected story, current index, timer, open/close state

There is no visible persistence layer, server API, or external data dependency.

12. What to draw in an architecture diagram

A good diagram would show:

- the Next.js page shell as the top-level container

- stories.ts as the static source feeding the page

- StoriesList as the selection entry point

- StoriesModal as the central interaction hub

- Progressbar as a child of the modal viewer

- react-modal and GSAP as supporting libraries around the modal layer

- Tailwind/global CSS as the styling layer underneath the UI components