# victorh-silveira/insta-follow-manager architecture

> Architecture diagram of the GitHub repository victorh-silveira/insta-follow-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/victorh-silveira/insta-follow-manager
- Repository: https://github.com/victorh-silveira/insta-follow-manager

## Overview

Insta Follow Manager is a full-stack Instagram relationship triage app. Users authenticate, synchronize followers/following, browse cached lists by relationship type and display-name bucket, and unfollow or remove followers. The frontend is a Next.js UI over a FastAPI backend; application use cases coordinate Instagram and repository ports, with configurable Instagram adapters and SQLite caching. The README documents capabilities beyond the sampled excerpts; frontend-to-API wiring and some unsampled route details are therefore shown only as unverified links or omitted.

Main entry points: [`backend/src/presentation/api/dependencies.py`](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/presentation/api/dependencies.py) (Dependency wiring), [`frontend/src/services/relationshipApi.ts`](https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/services/relationshipApi.ts) (Relationship API client), [`backend/src/presentation/api/routes/relationships.py`](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/presentation/api/routes/relationships.py) (Relationship routes), [`backend/src/infrastructure/persistence/sqlite_profile_repository.py`](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/infrastructure/persistence/sqlite_profile_repository.py) (SQLite profile store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_webapp["Triage screen<br/>[page.tsx]"]
  node_loginui["Instagram login"]
  node_syncui["Sync controls<br/>[SyncHeader.tsx]"]
  node_tabs["Relationship tabs"]
  node_alphabet["Bucket filter<br/>[AlphabetBar.tsx]"]
  node_profileui["Profile actions<br/>[ProfileCard.tsx]"]
  node_api_client["Relationship API client<br/>[relationshipApi.ts]"]
end

subgraph group_api["API presentation"]
  node_app["FastAPI app<br/>[main.py]"]
  node_authroute["Auth routes<br/>[auth.py]"]
  node_relroute["Relationship routes<br/>[relationships.py]"]
  node_healthroute["Health route<br/>[health.py]"]
  node_di["Dependency wiring<br/>[dependencies.py]"]
end

subgraph group_application["Use cases and domain"]
  node_auth["Instagram authentication<br/>[auth_instagram.py]"]
  node_sync["Relationship sync"]
  node_listing["Filtered listing"]
  node_unfollow["Unfollow action"]
  node_removefollower["Remove follower<br/>[remove_follower.py]"]
  node_profile["Profile model"]
  node_namebucket["Name buckets<br/>[name_bucket.py]"]
  node_gatewayport["Instagram gateway port"]
  node_repoport["Profile repository port"]
end

subgraph group_infrastructure["Adapters and persistence"]
  node_instagrapi["Instagrapi adapter"]
  node_mock["Mock adapter"]
  node_sqlite_repo["SQLite profile store"]
  node_database[("SQLite database<br/>[database.py]")]
end

node_user(("Manager"))
node_instagram(("Instagram"))

node_user -->|"uses"| node_webapp
node_webapp -.->|"requests data"| node_api_client
node_loginui -.->|"requests auth"| node_api_client
node_syncui -.->|"requests sync"| node_api_client
node_tabs -.->|"requests lists"| node_api_client
node_alphabet -.->|"filters lists"| node_api_client
node_profileui -.->|"requests actions"| node_api_client
node_api_client -.->|"calls API"| node_authroute
node_api_client -.->|"calls API"| node_relroute
node_app -->|"registers"| node_authroute
node_app -->|"registers"| node_relroute
node_app -->|"registers"| node_healthroute
node_authroute -->|"invokes"| node_auth
node_relroute -->|"invokes"| node_sync
node_relroute -->|"invokes"| node_listing
node_relroute -->|"invokes"| node_unfollow
node_relroute -->|"invokes"| node_removefollower
node_di -->|"constructs"| node_auth
node_di -->|"constructs"| node_sync
node_di -->|"constructs"| node_listing
node_di -->|"constructs"| node_unfollow
node_di -->|"constructs"| node_removefollower
node_di -->|"selects adapter"| node_instagrapi
node_di -->|"selects adapter"| node_mock
node_di -->|"constructs"| node_sqlite_repo
node_sync -->|"fetches relationships"| node_gatewayport
node_sync -->|"replaces cache"| node_repoport
node_listing -->|"queries profiles"| node_repoport
node_unfollow -->|"unfollows account"| node_gatewayport
node_unfollow -->|"updates profile"| node_repoport
node_removefollower -->|"removes follower"| node_gatewayport
node_removefollower -->|"updates profile"| node_repoport
node_auth -->|"authenticates"| node_gatewayport
node_profile -->|"derives bucket"| node_namebucket
node_sqlite_repo -->|"reads and writes"| node_database
node_sqlite_repo -->|"maps records"| node_profile
node_sqlite_repo -->|"uses buckets"| node_namebucket
node_instagrapi -.->|"communicates with"| node_instagram

click node_webapp "https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/app/page.tsx"
click node_loginui "https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/components/InstagramLoginCard.tsx"
click node_syncui "https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/components/SyncHeader.tsx"
click node_tabs "https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/components/RelationshipTabs.tsx"
click node_alphabet "https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/components/AlphabetBar.tsx"
click node_profileui "https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/components/ProfileCard.tsx"
click node_api_client "https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/services/relationshipApi.ts"
click node_app "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/presentation/main.py"
click node_authroute "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/presentation/api/routes/auth.py"
click node_relroute "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/presentation/api/routes/relationships.py"
click node_healthroute "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/presentation/api/routes/health.py"
click node_di "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/presentation/api/dependencies.py"
click node_auth "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/application/use_cases/auth_instagram.py"
click node_sync "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/application/use_cases/sync_relationships.py"
click node_listing "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/application/use_cases/list_profiles_by_bucket.py"
click node_unfollow "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/application/use_cases/unfollow_profile.py"
click node_removefollower "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/application/use_cases/remove_follower.py"
click node_profile "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/domain/entities/instagram_profile.py"
click node_namebucket "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/domain/value_objects/name_bucket.py"
click node_gatewayport "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/domain/gateways/instagram_gateway.py"
click node_repoport "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/domain/repositories/profile_repository.py"
click node_instagrapi "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/infrastructure/gateways/instagrapi_gateway.py"
click node_mock "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/infrastructure/gateways/mock_instagram_gateway.py"
click node_sqlite_repo "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/infrastructure/persistence/sqlite_profile_repository.py"
click node_database "https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/infrastructure/persistence/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_webapp,node_loginui,node_syncui,node_tabs,node_alphabet,node_profileui,node_api_client toneBlue
class node_app,node_authroute,node_relroute,node_healthroute,node_di toneAmber
class node_auth,node_sync,node_listing,node_unfollow,node_removefollower,node_profile,node_namebucket,node_gatewayport,node_repoport toneMint
class node_instagrapi,node_mock,node_sqlite_repo,node_database toneRose
class node_user,node_instagram toneIndigo
```

## Components

### Web interface

- [Triage screen](https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Instagram login](https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/components/InstagramLoginCard.tsx): `frontend/src/components/InstagramLoginCard.tsx`
- [Sync controls](https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/components/SyncHeader.tsx): `frontend/src/components/SyncHeader.tsx`
- [Relationship tabs](https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/components/RelationshipTabs.tsx): `frontend/src/components/RelationshipTabs.tsx`
- [Bucket filter](https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/components/AlphabetBar.tsx): `frontend/src/components/AlphabetBar.tsx`
- [Profile actions](https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/components/ProfileCard.tsx): `frontend/src/components/ProfileCard.tsx`
- [Relationship API client](https://github.com/victorh-silveira/insta-follow-manager/blob/main/frontend/src/services/relationshipApi.ts): `frontend/src/services/relationshipApi.ts`

### API presentation

- [FastAPI app](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/presentation/main.py): `backend/src/presentation/main.py`
- [Auth routes](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/presentation/api/routes/auth.py): `backend/src/presentation/api/routes/auth.py`
- [Relationship routes](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/presentation/api/routes/relationships.py): `backend/src/presentation/api/routes/relationships.py`
- [Health route](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/presentation/api/routes/health.py): `backend/src/presentation/api/routes/health.py`
- [Dependency wiring](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/presentation/api/dependencies.py): `backend/src/presentation/api/dependencies.py`

### Use cases and domain

- [Instagram authentication](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/application/use_cases/auth_instagram.py): `backend/src/application/use_cases/auth_instagram.py`
- [Relationship sync](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/application/use_cases/sync_relationships.py): `backend/src/application/use_cases/sync_relationships.py`
- [Filtered listing](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/application/use_cases/list_profiles_by_bucket.py): `backend/src/application/use_cases/list_profiles_by_bucket.py`
- [Unfollow action](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/application/use_cases/unfollow_profile.py): `backend/src/application/use_cases/unfollow_profile.py`
- [Remove follower](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/application/use_cases/remove_follower.py): `backend/src/application/use_cases/remove_follower.py`
- [Profile model](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/domain/entities/instagram_profile.py): `backend/src/domain/entities/instagram_profile.py`
- [Name buckets](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/domain/value_objects/name_bucket.py): `backend/src/domain/value_objects/name_bucket.py`
- [Instagram gateway port](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/domain/gateways/instagram_gateway.py): `backend/src/domain/gateways/instagram_gateway.py`
- [Profile repository port](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/domain/repositories/profile_repository.py): `backend/src/domain/repositories/profile_repository.py`

### Adapters and persistence

- [Instagrapi adapter](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/infrastructure/gateways/instagrapi_gateway.py): `backend/src/infrastructure/gateways/instagrapi_gateway.py`
- [Mock adapter](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/infrastructure/gateways/mock_instagram_gateway.py): `backend/src/infrastructure/gateways/mock_instagram_gateway.py`
- [SQLite profile store](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/infrastructure/persistence/sqlite_profile_repository.py): `backend/src/infrastructure/persistence/sqlite_profile_repository.py`
- [SQLite database](https://github.com/victorh-silveira/insta-follow-manager/blob/main/backend/src/infrastructure/persistence/database.py): `backend/src/infrastructure/persistence/database.py`

### Other components

- **Manager**
- **Instagram**

## Connections

- Manager → Triage screen: uses (evidence: `README.md`)
- Triage screen → Relationship API client: requests data
- Instagram login → Relationship API client: requests auth
- Sync controls → Relationship API client: requests sync
- Relationship tabs → Relationship API client: requests lists
- Bucket filter → Relationship API client: filters lists
- Profile actions → Relationship API client: requests actions
- Relationship API client → Auth routes: calls API
- Relationship API client → Relationship routes: calls API
- FastAPI app → Auth routes: registers (evidence: `backend/src/presentation/main.py`)
- FastAPI app → Relationship routes: registers (evidence: `backend/src/presentation/main.py`)
- FastAPI app → Health route: registers (evidence: `backend/src/presentation/main.py`)
- Auth routes → Instagram authentication: invokes (evidence: `backend/src/presentation/api/routes/auth.py`)
- Relationship routes → Relationship sync: invokes (evidence: `backend/src/presentation/api/routes/relationships.py`)
- Relationship routes → Filtered listing: invokes (evidence: `backend/src/presentation/api/routes/relationships.py`)
- Relationship routes → Unfollow action: invokes (evidence: `backend/src/presentation/api/routes/relationships.py`)
- Relationship routes → Remove follower: invokes (evidence: `backend/src/presentation/api/routes/relationships.py`)
- Dependency wiring → Instagram authentication: constructs (evidence: `backend/src/presentation/api/dependencies.py`)
- Dependency wiring → Relationship sync: constructs (evidence: `backend/src/presentation/api/dependencies.py`)
- Dependency wiring → Filtered listing: constructs (evidence: `backend/src/presentation/api/dependencies.py`)
- Dependency wiring → Unfollow action: constructs (evidence: `backend/src/presentation/api/dependencies.py`)
- Dependency wiring → Remove follower: constructs (evidence: `backend/src/presentation/api/dependencies.py`)
- Dependency wiring → Instagrapi adapter: selects adapter (evidence: `backend/src/presentation/api/dependencies.py`)
- Dependency wiring → Mock adapter: selects adapter (evidence: `backend/src/presentation/api/dependencies.py`)
- Dependency wiring → SQLite profile store: constructs (evidence: `backend/src/presentation/api/dependencies.py`)
- Relationship sync → Instagram gateway port: fetches relationships (evidence: `backend/src/application/use_cases/sync_relationships.py`)
- Relationship sync → Profile repository port: replaces cache (evidence: `backend/src/application/use_cases/sync_relationships.py`)
- Filtered listing → Profile repository port: queries profiles (evidence: `backend/src/application/use_cases/list_profiles_by_bucket.py`)
- Unfollow action → Instagram gateway port: unfollows account (evidence: `backend/src/application/use_cases/unfollow_profile.py`)
- Unfollow action → Profile repository port: updates profile (evidence: `backend/src/application/use_cases/unfollow_profile.py`)
- Remove follower → Instagram gateway port: removes follower (evidence: `backend/src/application/use_cases/remove_follower.py`)
- Remove follower → Profile repository port: updates profile (evidence: `backend/src/application/use_cases/remove_follower.py`)
- Instagram authentication → Instagram gateway port: authenticates (evidence: `backend/src/application/use_cases/auth_instagram.py`)
- Profile model → Name buckets: derives bucket (evidence: `backend/src/domain/entities/instagram_profile.py`)
- SQLite profile store → SQLite database: reads and writes (evidence: `backend/src/infrastructure/persistence/sqlite_profile_repository.py`)
- SQLite profile store → Profile model: maps records (evidence: `backend/src/infrastructure/persistence/sqlite_profile_repository.py`)
- SQLite profile store → Name buckets: uses buckets (evidence: `backend/src/infrastructure/persistence/sqlite_profile_repository.py`)
- Instagrapi adapter → Instagram: communicates with
