Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
341 lines (216 loc) · 4.44 KB

ARCHITECTURE.md

File metadata and controls

341 lines (216 loc) · 4.44 KB
Raw

Attnsn Architecture

Vision

Build a daily intelligence system for software engineers building AI products.

The goal is not to aggregate news.

The goal is to help builders confidently answer one question:

"What happened today that is actually worth my attention?"

Problem

Software engineers consume information from many places:

  • X
  • Hacker News
  • GitHub
  • AI company blogs
  • Product launches

Most of this information is noise.

Existing platforms optimize for engagement rather than helping users prioritize what deserves their limited attention.

This leads to:

Information Overload

↓

Attention Fragmentation

↓

Decision Paralysis

↓

Less Time Building

Product Philosophy

Help users think.

Don't think for them.

Attnsn should:

  • Reduce noise
  • Organize information
  • Provide context
  • Explain why something matters

Attnsn should not:

  • Replace the user's judgment
  • Generate endless content
  • Maximize engagement

MVP

Audience

Software engineers building AI products.

Habit

Spend five minutes every morning.

Outcome

Understand the few things that actually matter.

Sources

The MVP collects information from:

  • AI company blogs
  • GitHub Releases
  • GitHub Trending
  • Hacker News
  • Curated X accounts

Additional sources may be added after validation.

High-Level Architecture

                   Daily Cron
                        │
                        ▼
                 Collect Raw Data
                        │
                        ▼
            Extract & Normalize
                        │
                        ▼
         Identify Events & Rank Importance
                        │
                        ▼
              Generate Daily Brief
                        │
                        ▼
                   Publish Brief

Pipeline

1. Collect

Fetch raw information from every source.

Output:

RawItems[]

2. Extract & Normalize

Each source has its own extractor.

The extractor converts raw source data into a common format.

Output:

InformationItems[]

3. Identify Events & Rank

The LLM:

  • merges duplicate events
  • identifies important events
  • removes insignificant information
  • ranks events by importance

Output:

RankedEvents[]

4. Generate Brief

Transform ranked events into readable brief cards.

Each card answers:

  • What happened?
  • Why does it matter?
  • Who should care?
  • Where did this information come from?

Output:

Brief

5. Publish

Persist the generated brief.

Initially:

  • MongoDB

Later:

  • Personalized feeds
  • Notifications
  • Weekly digests

Backend Layers

Pipeline
    │
    ▼
Collectors
    │
    ▼
Extractors
    │
    ▼
Providers
    │
    ▼
External Services

Cross-cutting concerns:

  • Error handling
  • Retry logic
  • Logging
  • Validation
  • Environment

Repository Structure

apps/

    backend/

    web/

Backend responsibilities:

  • Collect information
  • Generate intelligence
  • Expose APIs

Frontend responsibilities:

  • Display the daily brief

Domain Objects

The system revolves around four entities.

RawItem

Raw data collected from a source.

Example:

  • Tweet
  • Blog article
  • GitHub release

InformationItem

Normalized piece of information extracted from a RawItem.

RankedEvent

An event representing one or more related InformationItems.

Contains:

  • importance
  • confidence
  • supporting sources

Brief

The final daily intelligence report shown to users.

Providers

Providers encapsulate communication with external services.

Examples:

  • Gemini
  • Firecrawl
  • Tavily
  • GitHub
  • AnyAPI

The rest of the application never communicates with external APIs directly.

Design Principles

  • Keep the pipeline modular.
  • Keep prompts separate from code.
  • Prefer composition over abstraction.
  • Introduce abstractions only after repetition.
  • Keep source-specific logic isolated.
  • Optimize for clarity over cleverness.

Future Roadmap

Potential future capabilities:

  • User accounts
  • Personalized ranking
  • Follow topics
  • Follow companies
  • Saved events
  • Search
  • Weekly digests
  • Notifications
  • Discovery engine
  • AI-powered exploration

These features should not influence the MVP implementation until the core pipeline has been validated.

Current Goal

Build the smallest system capable of generating one trustworthy daily brief for AI builders.

Everything else is secondary.