StackLens

StackLens is a full-stack log aggregation and monitoring dashboard built with Typescript and a modern PERN stack.
It allows services to push logs into a centralized system and provides powerful filtering, searching, pagination, and analytics.

Built to simulate a production-style logging system with real-time filtering and responsive UI.

The system exposes a log ingestion API where services can push structured logs. These logs are stored in PostgreSQL and analyzed through a React dashboard powered by backend analytics endpoints.

---

Features

• ☐ Centralized log storage
• ⌕ Search logs with debounce
• ⌁ Filter by service & log level (debug, info, warn, error)
• ◷ Date range filtering
• ◳ Analytics dashboard (log distribution & trends)
• ⎘ Pagination
• ◻ Fully responsive UI (mobile-first)
• ◐ Dark mode support
• ⇄ Smooth route transitions with Framer Motion
• ⛨ Secure backend with CORS & environment variables
• Authentication
• Multi User Support

---

StackLens Demo

4kstacklens.mp4

---

Architecture

Service → Log Ingestion API → Express Server → PostgreSQL → React Dashboard

1. Services send logs to the backend using a REST API
2. The Express server validates and stores logs in PostgreSQL
3. The frontend dashboard fetches logs through API endpoints
4. Logs are visualized through charts and filtering tools

---

Tech Stack

Layer	Technology
Frontend	React, TypeScript, TanStack Query, Recharts
Backend	Node.js, Express, TypeScript
Database	PostgreSQL
Deployment	Render (backend), Supabase (database)

---

Project Structure

stacklens/
│
├── frontend/        # React + TypeScript dashboard
├── backend/         # Express + TypeScript API
└── README.md

---

Log Format

Logs follow a structured JSON format:

{
  "service": "auth-service",
  "level": "error",
  "message": "User authentication failed",
  "metadata": { "ip": "192.168.1.10", "user_id": "123" },
  "timestamp": "2026-03-04T10:30:00Z",
  "created_at": "2026-03-04T10:30:00Z"
}

Supported severity levels: debug · info · warn · error

---

API Reference

Send a Log

POST /logs

Request body:

{
  "service": "deploy-service",
  "level": "warn",
  "message": "avoid unnecessary bloat",
  "metadata": { "user_id": "123", "ip": "192.168.1.10" }
}

The server stores the log in db and fetches it making immediately available for search and analytics.

---

Running Locally

1. Clone the repository

git clone https://github.com/Whitfrost21/stacklens.git
cd stacklens

2. Set up the backend

cd backend
npm install

Create a .env file:

DATABASE_URL=your_postgres_url
PORT=5000

Start the server:

npm run dev

3. Set up the frontend

cd frontend
npm install
npm run dev

The React app will be running at http://localhost:5173.

---

Roadmap

• Real-time log streaming
• Log ingestion agents
• Alerting and notifications
• Distributed tracing support

---

Learning Goals

This project was built to explore:

• Observability concepts and log aggregation pipelines
• API design for log ingestion
• Data querying and analytics at scale
• Building dashboards for monitoring distributed systems

---

Contributing

Contributions are welcome. Feel free to open issues or submit pull requests.