# timelinize/timelinize architecture

> Architecture diagram of the GitHub repository timelinize/timelinize, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/timelinize/timelinize
- Repository: https://github.com/timelinize/timelinize

## Overview

##### Main System Components

a) Frontend Layer
- Single-page web application (evident from frontend/resources/js/spa.js)
- Multiple views (dashboard, timeline, map, gallery, conversations, etc.)
- Static resources (CSS, JS, images)

b) Backend Layer (Go-based)
- Main application server (tlzapp package)
- Timeline processing engine (timeline package)
- OAuth2 client system (oauth2client package)
- Data source processors (datasources package)

c) Storage Layer
- SQLite database (referenced in timeline/schema.sql)
- File system storage for media and imported data

##### Key Relationships to Highlight

a) Data Flow
- External services → OAuth2 Client → Data Source Processors
- Data Source Processors → Timeline Processing Engine → Database
- Frontend → Backend API Endpoints → Timeline Engine
- Timeline Engine ↔ File System Storage

b) Processing Flow
- Import Process: Raw Data → Data Source Processors → Timeline Processing
- Query Process: User Request → API → Timeline Engine → Database/Files → Response

##### Specific Components

Data Sources (group these visually):
- Social Media (Facebook, Twitter, Instagram)
- Communication (iMessage, Gmail, Telegram)
- Location (Google Location, GPX, NMEA)
- Media (Photos, Videos)
- Contacts (Apple Contacts, vCard)

Processing Components:
- Entity Recognition System
- Location Processing
- Media Processing
- Timeline Aggregation
- Search Infrastructure

##### Important Subsystems to Detail

a) Data Import Pipeline
- File recognition
- Format processing
- Entity extraction
- Timeline integration

b) Query Processing
- User interface requests
- API routing
- Data aggregation
- Response formatting

##### Technical Details

Annotations for:
- Go-based backend
- SQLite database
- HTTP/JSON API
- OAuth2 authentication
- File system organization
- Browser-based frontend

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and classes
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef backend fill:#2ecc71,stroke:#27ae60,color:white
    classDef storage fill:#e74c3c,stroke:#c0392b,color:white
    classDef processor fill:#f1c40f,stroke:#f39c12,color:black
    classDef external fill:#9b59b6,stroke:#8e44ad,color:white
    
    %% Frontend Layer
    subgraph Frontend
        SPA["Single Page Application"]
        Views["Views (Dashboard/Timeline/Map/Gallery)"]
        StaticRes["Static Resources"]
    end
    class SPA,Views,StaticRes frontend
    
    %% Backend Layer
    subgraph Backend
        AppServer["Application Server"]
        TimelineEngine["Timeline Processing Engine"]
        OAuth2System["OAuth2 Client System"]
    end
    class AppServer,TimelineEngine,OAuth2System backend
    
    %% Storage Layer
    subgraph Storage
        DB[(SQLite Database)]
        FileSystem["File System Storage"]
    end
    class DB,FileSystem storage
    
    %% Data Source Processors
    subgraph DataProcessors
        SocialMedia["Social Media Processors"]
        Communication["Communication Processors"]
        Location["Location Processors"]
        Media["Media Processors"]
        Contacts["Contact Processors"]
    end
    class SocialMedia,Communication,Location,Media,Contacts processor
    
    %% External Services
    subgraph ExternalServices
        Facebook["Facebook"]
        Twitter["Twitter"]
        Gmail["Gmail"]
        Instagram["Instagram"]
        iMessage["iMessage"]
    end
    class Facebook,Twitter,Gmail,Instagram,iMessage external
    
    %% Processing Components
    subgraph ProcessingSystem
        EntityRecog["Entity Recognition"]
        LocProc["Location Processing"]
        MediaProc["Media Processing"]
        TimelineAgg["Timeline Aggregation"]
        SearchInfra["Search Infrastructure"]
    end
    class EntityRecog,LocProc,MediaProc,TimelineAgg,SearchInfra processor
    
    %% Relationships
    ExternalServices --> OAuth2System
    OAuth2System --> DataProcessors
    DataProcessors --> TimelineEngine
    TimelineEngine --> DB
    TimelineEngine --> FileSystem
    SPA --> AppServer
    AppServer --> TimelineEngine
    ProcessingSystem --> TimelineEngine
    
    %% Click events
    click SPA "https://github.com/timelinize/timelinize/blob/main/frontend/resources/js/spa.js"
    click Views "https://github.com/timelinize/timelinize/tree/main/frontend/pages"
    click StaticRes "https://github.com/timelinize/timelinize/tree/main/frontend/resources"
    click AppServer "https://github.com/timelinize/timelinize/blob/main/tlzapp/app.go"
    click TimelineEngine "https://github.com/timelinize/timelinize/blob/main/timeline/timeline.go"
    click OAuth2System "https://github.com/timelinize/timelinize/blob/main/oauth2client/oauth2.go"
    click SocialMedia "https://github.com/timelinize/timelinize/tree/main/datasources"
    click DB "https://github.com/timelinize/timelinize/blob/main/timeline/schema.sql"
    click FileSystem "https://github.com/timelinize/timelinize/blob/main/timeline/itemfiles.go"
    click EntityRecog "https://github.com/timelinize/timelinize/blob/main/timeline/entities.go"
    click LocProc "https://github.com/timelinize/timelinize/blob/main/datasources/googlelocation/locproc.go"
    click MediaProc "https://github.com/timelinize/timelinize/blob/main/datasources/media/media.go"
    click SearchInfra "https://github.com/timelinize/timelinize/blob/main/timeline/search.go"
```
