# yossiwolfe/tabs-group-sync architecture

> Architecture diagram of the GitHub repository yossiwolfe/tabs-group-sync, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yossiwolfe/tabs-group-sync
- Repository: https://github.com/yossiwolfe/tabs-group-sync

## Overview

Tab Groups Project is a FastAPI service for storing and syncing tab groups across devices. Clients call the group API to create, update, delete, or retrieve groups; retrieval can filter by modification time, and deletion is represented by a flag. The API validates request and response data with Pydantic schemas and uses SQLAlchemy sessions to persist ORM models in SQLite. The README describes real-time syncing, but the sampled implementation exposes timestamp-filtered HTTP retrieval rather than a real-time transport; tab schemas and models exist without sampled tab endpoints.

Main entry points: [`src/tab_groups_proj/main.py`](https://github.com/yossiwolfe/tabs-group-sync/blob/main/src/tab_groups_proj/main.py) (Group API), [`src/tab_groups_proj/database.py`](https://github.com/yossiwolfe/tabs-group-sync/blob/main/src/tab_groups_proj/database.py) (DB Sessions), [`src/tab_groups_proj/models.py`](https://github.com/yossiwolfe/tabs-group-sync/blob/main/src/tab_groups_proj/models.py) (Tab Models), [`src/tab_groups_proj/schemas.py`](https://github.com/yossiwolfe/tabs-group-sync/blob/main/src/tab_groups_proj/schemas.py) (API Schemas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_group_api["Group API<br/>[main.py]"]
end

subgraph group_contracts["Data Contracts"]
  node_schemas["API Schemas<br/>[schemas.py]"]
end

subgraph group_persistence["Persistence"]
  node_orm_models["Tab Models<br/>[models.py]"]
  node_db_sessions["DB Sessions<br/>[database.py]"]
  node_sqlite[("SQLite Store")]
end

node_client(("Sync Client"))

node_client -->|"sends requests"| node_group_api
node_group_api -->|"validates and serializes"| node_schemas
node_group_api -->|"gets sessions"| node_db_sessions
node_group_api -->|"queries and mutates"| node_orm_models
node_db_sessions -->|"creates tables"| node_orm_models
node_db_sessions -->|"opens and persists"| node_sqlite
node_group_api -->|"returns group data"| node_client

click node_group_api "https://github.com/yossiwolfe/tabs-group-sync/blob/main/src/tab_groups_proj/main.py"
click node_schemas "https://github.com/yossiwolfe/tabs-group-sync/blob/main/src/tab_groups_proj/schemas.py"
click node_orm_models "https://github.com/yossiwolfe/tabs-group-sync/blob/main/src/tab_groups_proj/models.py"
click node_db_sessions "https://github.com/yossiwolfe/tabs-group-sync/blob/main/src/tab_groups_proj/database.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_group_api,node_client toneBlue
class node_schemas toneAmber
class node_orm_models,node_db_sessions,node_sqlite toneMint
```

## Components

### HTTP API

- [Group API](https://github.com/yossiwolfe/tabs-group-sync/blob/main/src/tab_groups_proj/main.py): `src/tab_groups_proj/main.py`

### Data Contracts

- [API Schemas](https://github.com/yossiwolfe/tabs-group-sync/blob/main/src/tab_groups_proj/schemas.py): `src/tab_groups_proj/schemas.py`

### Persistence

- [Tab Models](https://github.com/yossiwolfe/tabs-group-sync/blob/main/src/tab_groups_proj/models.py): `src/tab_groups_proj/models.py`
- [DB Sessions](https://github.com/yossiwolfe/tabs-group-sync/blob/main/src/tab_groups_proj/database.py): `src/tab_groups_proj/database.py`
- **SQLite Store**

### Other components

- **Sync Client**

## Connections

- Sync Client → Group API: sends requests (evidence: `src/tab_groups_proj/main.py`)
- Group API → API Schemas: validates and serializes (evidence: `src/tab_groups_proj/main.py`)
- Group API → DB Sessions: gets sessions (evidence: `src/tab_groups_proj/main.py`)
- Group API → Tab Models: queries and mutates (evidence: `src/tab_groups_proj/main.py`)
- DB Sessions → Tab Models: creates tables (evidence: `src/tab_groups_proj/database.py`)
- DB Sessions → SQLite Store: opens and persists (evidence: `src/tab_groups_proj/database.py`)
- Group API → Sync Client: returns group data (evidence: `src/tab_groups_proj/main.py`)
