# diediegodie/tattoo_studio_system_v4 architecture

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

- Interactive diagram: https://gitdiagram.com/diediegodie/tattoo_studio_system_v4
- Repository: https://github.com/diediegodie/tattoo_studio_system_v4

## Overview

This is a Flask-based tattoo-studio operations platform. Studio staff use its web/API routes to manage clients, appointments and sessions, inventory, payments, expenses, and financial statements; the system also supports search, reporting, calendar synchronization, JotForm client intake, OAuth login, and backups. The documented architecture places Flask between users and PostgreSQL, with Google and JotForm integrations. Sampled source confirms app route registration, inventory controller-to-service/repository calls, and direct database work in selected controllers/services; unsampled feature wiring is kept at subsystem level rather than inferred.

Main entry points: [`backend/app/main.py`](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/main.py) (Flask app), [`backend/app/db/base.py`](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/db/base.py) (PostgreSQL), [`backend/app/services/client_service.py`](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/client_service.py) (Client service), [`backend/app/controllers/auth_controller.py`](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/auth_controller.py) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application"]
  node_flask["Flask app<br/>[main.py]"]
  node_auth_routes["Authentication<br/>[auth_controller.py]"]
  node_api_routes["API routes<br/>[api_controller.py]"]
end

subgraph group_studio_ops["Studio operations"]
  node_client_routes["Client routes"]
  node_session_routes["Session routes"]
  node_inventory_routes["Inventory routes"]
  node_inventory_service["Inventory service"]
  node_inventory_repo["Inventory repository"]
  node_client_service["Client service<br/>[client_service.py]"]
  node_client_repo["Client repository<br/>[client_repo.py]"]
  node_jotform_service["JotForm intake<br/>[jotform_service.py]"]
  node_calendar_routes["Calendar routes"]
  node_calendar_service["Calendar service"]
  node_search_routes["Search routes"]
  node_search_service["Global search<br/>[search_service.py]"]
end

subgraph group_finance["Finance"]
  node_finance_routes["Finance routes"]
  node_expense_routes["Expense routes"]
  node_history_routes["History and statements"]
  node_statement_service["Statement processing"]
  node_reports_routes["Reports"]
end

subgraph group_platform["Platform services"]
  node_postgres[("PostgreSQL<br/>[base.py]")]
  node_oauth["Google OAuth<br/>[google_login.py]"]
  node_backup_service["Backup service<br/>[backup_service.py]"]
end

node_staff(("Studio staff"))
node_jotform["JotForm API"]
node_google_calendar["Google Calendar"]

node_staff -->|"uses"| node_flask
node_flask -->|"dispatches"| node_auth_routes
node_flask -->|"dispatches"| node_api_routes
node_flask -->|"dispatches"| node_client_routes
node_flask -->|"dispatches"| node_session_routes
node_flask -->|"dispatches"| node_inventory_routes
node_flask -->|"dispatches"| node_calendar_routes
node_flask -->|"dispatches"| node_finance_routes
node_flask -->|"dispatches"| node_expense_routes
node_flask -->|"dispatches"| node_history_routes
node_flask -->|"dispatches"| node_search_routes
node_flask -->|"dispatches"| node_reports_routes
node_auth_routes -->|"starts login"| node_oauth
node_oauth -->|"stores tokens"| node_postgres
node_client_routes -->|"manages clients"| node_client_service
node_client_service -->|"persists clients"| node_client_repo
node_jotform_service -.->|"fetches submissions"| node_jotform
node_client_service -.->|"synchronizes intake"| node_jotform_service
node_session_routes -->|"reads and writes"| node_postgres
node_inventory_routes -->|"calls"| node_inventory_service
node_inventory_service -->|"persists items"| node_inventory_repo
node_inventory_repo -->|"reads and writes"| node_postgres
node_calendar_routes -->|"calls"| node_calendar_service
node_calendar_service -.->|"syncs events"| node_google_calendar
node_finance_routes -->|"reads and writes"| node_postgres
node_expense_routes -->|"reads and writes"| node_postgres
node_history_routes -->|"reads and writes"| node_postgres
node_api_routes -->|"generates statements"| node_statement_service
node_statement_service -->|"processes records"| node_postgres
node_search_routes -->|"searches"| node_search_service
node_search_service -->|"queries records"| node_postgres
node_reports_routes -->|"reads reports data"| node_postgres
node_backup_service -->|"backs up data"| node_postgres

click node_flask "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/auth_controller.py"
click node_api_routes "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/api_controller.py"
click node_client_routes "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/client_controller.py"
click node_session_routes "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/sessoes_controller.py"
click node_inventory_routes "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/inventory_controller.py"
click node_inventory_service "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/inventory_service.py"
click node_inventory_repo "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/repositories/inventory_repository.py"
click node_client_service "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/client_service.py"
click node_client_repo "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/repositories/client_repo.py"
click node_jotform_service "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/jotform_service.py"
click node_calendar_routes "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/calendar_controller.py"
click node_calendar_service "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/google_calendar_service.py"
click node_finance_routes "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/financeiro_controller.py"
click node_expense_routes "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/gastos_controller.py"
click node_history_routes "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/historico_controller.py"
click node_statement_service "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/extrato_generation.py"
click node_search_routes "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/search_controller.py"
click node_search_service "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/search_service.py"
click node_reports_routes "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/reports_controller.py"
click node_postgres "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/db/base.py"
click node_oauth "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/auth/google_login.py"
click node_backup_service "https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/backup_service.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_flask,node_auth_routes,node_api_routes toneBlue
class node_client_routes,node_session_routes,node_inventory_routes,node_inventory_service,node_inventory_repo,node_client_service,node_client_repo,node_jotform_service,node_calendar_routes,node_calendar_service,node_search_routes,node_search_service toneAmber
class node_finance_routes,node_expense_routes,node_history_routes,node_statement_service,node_reports_routes,node_jotform toneMint
class node_postgres,node_oauth,node_backup_service toneRose
class node_staff,node_google_calendar toneIndigo
```

## Components

### Application

- [Flask app](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/auth_controller.py): `backend/app/controllers/auth_controller.py`
- [API routes](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/api_controller.py): `backend/app/controllers/api_controller.py`

### Studio operations

- [Client routes](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/client_controller.py): `backend/app/controllers/client_controller.py`
- [Session routes](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/sessoes_controller.py): `backend/app/controllers/sessoes_controller.py`
- [Inventory routes](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/inventory_controller.py): `backend/app/controllers/inventory_controller.py`
- [Inventory service](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/inventory_service.py): `backend/app/services/inventory_service.py`
- [Inventory repository](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/repositories/inventory_repository.py): `backend/app/repositories/inventory_repository.py`
- [Client service](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/client_service.py): `backend/app/services/client_service.py`
- [Client repository](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/repositories/client_repo.py): `backend/app/repositories/client_repo.py`
- [JotForm intake](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/jotform_service.py): `backend/app/services/jotform_service.py`
- [Calendar routes](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/calendar_controller.py): `backend/app/controllers/calendar_controller.py`
- [Calendar service](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/google_calendar_service.py): `backend/app/services/google_calendar_service.py`
- [Search routes](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/search_controller.py): `backend/app/controllers/search_controller.py`
- [Global search](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/search_service.py): `backend/app/services/search_service.py`

### Finance

- [Finance routes](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/financeiro_controller.py): `backend/app/controllers/financeiro_controller.py`
- [Expense routes](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/gastos_controller.py): `backend/app/controllers/gastos_controller.py`
- [History and statements](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/historico_controller.py): `backend/app/controllers/historico_controller.py`
- [Statement processing](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/extrato_generation.py): `backend/app/services/extrato_generation.py`
- [Reports](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/controllers/reports_controller.py): `backend/app/controllers/reports_controller.py`

### Platform services

- [PostgreSQL](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/db/base.py): `backend/app/db/base.py`
- [Google OAuth](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/auth/google_login.py): `backend/app/auth/google_login.py`
- [Backup service](https://github.com/diediegodie/tattoo_studio_system_v4/blob/main/backend/app/services/backup_service.py): `backend/app/services/backup_service.py`

### Other components

- **Studio staff**
- **JotForm API**
- **Google Calendar**

## Connections

- Studio staff → Flask app: uses
- Flask app → Authentication: dispatches
- Flask app → API routes: dispatches
- Flask app → Client routes: dispatches
- Flask app → Session routes: dispatches
- Flask app → Inventory routes: dispatches
- Flask app → Calendar routes: dispatches
- Flask app → Finance routes: dispatches
- Flask app → Expense routes: dispatches
- Flask app → History and statements: dispatches
- Flask app → Search routes: dispatches
- Flask app → Reports: dispatches
- Authentication → Google OAuth: starts login
- Google OAuth → PostgreSQL: stores tokens
- Client routes → Client service: manages clients
- Client service → Client repository: persists clients
- JotForm intake → JotForm API: fetches submissions
- Client service → JotForm intake: synchronizes intake
- Session routes → PostgreSQL: reads and writes
- Inventory routes → Inventory service: calls
- Inventory service → Inventory repository: persists items
- Inventory repository → PostgreSQL: reads and writes
- Calendar routes → Calendar service: calls
- Calendar service → Google Calendar: syncs events
- Finance routes → PostgreSQL: reads and writes
- Expense routes → PostgreSQL: reads and writes
- History and statements → PostgreSQL: reads and writes
- API routes → Statement processing: generates statements
- Statement processing → PostgreSQL: processes records
- Search routes → Global search: searches
- Global search → PostgreSQL: queries records
- Reports → PostgreSQL: reads reports data
- Backup service → PostgreSQL: backs up data