Stories Reporter Dashboard

A social media analytics and content management dashboard built for a brand agency. Tracks Instagram/Meta Stories publications across multiple brand accounts, computes engagement metrics, generates compliance reports, and delivers them via email — all backed by a real-time NoSQL cloud database.

---

Features

• Publication CRUD — Create, edit, and soft-delete story records with full audit history (historialCambios). Soft deletion keeps records intact for auditing while hiding them from active views.
• Real-time sync — Firebase Realtime Database subscriptions keep all views up-to-date without manual refresh.
• Analytics dashboard — Engagement rates, compliance scoring, reach/impressions/interactions breakdowns, and period-over-period comparisons — all powered by a custom BI engine (useBICalculations, usePeriodComparison, useConsistencyScore).
• PDF report generation — Executive summary reports built client-side with @react-pdf/renderer, downloadable or sent via email (Gmail SMTP / nodemailer).
• Excel import — Upload .xlsx files to bulk-create or update publications. Handles Excel serial date conversion, theme normalization (accent stripping, title-case), and duplicate detection via composite key fecha|cuenta.
• Bulk calendar generator — Select accounts and a date range to auto-generate publication slots, optionally applying weekly content templates.
• Weekly content templates — Define per-account scheduling rules by day of week and reuse them across bulk operations.
• Cron task manager — UI for two scheduled tasks: a nightly state sweeper and a weekly report mailer (manual triggers + activation toggle; persistence WIP).
• Dynamic form reactions — Auto-fills week number, day name, and estaProgramado flag from the selected date and account config.
• Multi-account filtering — All views support filtering by brand account, date range, and publication status.

---

Tech Stack

Layer	Technology
Framework	Next.js 15 (App Router)
Language	TypeScript 5
UI Library	Ant Design 5 + Ant Design Charts
Styling	Tailwind CSS 4
Database	Firebase Realtime Database
PDF	@react-pdf/renderer
Email	Nodemailer (Gmail SMTP)
Excel	xlsx (SheetJS)
Date handling	Day.js (with ES locale)
Deployment	Vercel

---

Project Structure

src/
├── app/                  # Next.js pages (App Router)
│   ├── dashboard/        # Analytics & charts
│   ├── data/             # Publication CRUD table
│   ├── reportes/         # PDF generation & email
│   ├── funciones/        # Excel import & bulk calendar
│   ├── crontask/         # Scheduled task manager
│   └── api/send-email/   # Email API route
├── components/           # React UI components
├── context/              # PublicacionesContext (real-time data)
├── hooks/                # BI hooks (calculations, period comparison, consistency)
├── services/             # Firebase CRUD + template service
├── types/                # TypeScript models
└── utils/                # BI engine, state calc, PDF aggregators

---

Data Model

The core entity is a Publicacion (publication), which represents a single story posting slot for one brand account on one day:

{
  fecha: string;                  // DD-MM-YYYY
  cuenta: string;                 // Brand account ID
  estaProgramado: boolean;        // Was it scheduled?
  estaPublicado: boolean;         // Was it actually published?
  estado: string;                 // "Cumplido" | "Incumplido" | "Extra"
  items: Item[];                  // Reach, impressions, interactions per theme
  eliminado: boolean;             // Soft delete flag
  historialCambios: Change[];     // Full audit trail
}

State logic:

Scheduled	Published	Estado
No	No	Cumplido
Yes	Yes	Cumplido
Yes	No	Incumplido
No	Yes	Extra

---

Getting Started

Prerequisites

• Node.js 18+
• A Firebase project with Realtime Database enabled
• A Gmail account with an App Password for email delivery

Installation

git clone <repo-url>
cd dashboard
npm install

Environment Variables

Create a .env.local file at the root:

NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_DATABASE_URL=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=

GMAIL_USER=your@gmail.com
GMAIL_APP_PASSWORD=your_app_password

Run

npm run dev

Open http://localhost:3000.

---

Status

Active development. The project is in production use for a real client. Cron task persistence (Firebase-backed toggle state) is currently in progress.