# brunomygueldotcom/automatize-python-nailflows architecture

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

- Interactive diagram: https://gitdiagram.com/brunomygueldotcom/automatize-python-nailflows
- Repository: https://github.com/brunomygueldotcom/automatize-python-nailflows

## Overview

NailFlows is a FastAPI backend for nail designers to manage clients, services, appointments, invitation-based client registration, and calendar synchronization. The main workflow enters through API routes, delegates domain operations to services, and persists records through either in-memory or Supabase adapters; appointment operations also synchronize with the configured calendar. The README documents admin-protected routes and optional Google OAuth. Relationships are limited to excerpted code, SOURCE INDEX references, and README statements; unsampled subsystem internals are not assumed.

Main entry points: [`main.py`](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/main.py) (Application wiring), [`app/services/appointment_service.py`](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/services/appointment_service.py) (Appointment lifecycle), [`app/services/client_service.py`](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/services/client_service.py) (Client management), [`app/services/service_service.py`](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/services/service_service.py) (Service management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and setup"]
  node_app["Application wiring<br/>[main.py]"]
  node_client_api["Client routes"]
  node_appointment_api["Appointment and service routes<br/>[endpoints.py]"]
  node_registration_api["Registration routes"]
  node_google_api["Google OAuth routes"]
  node_security["Admin security<br/>[security.py]"]
end

subgraph group_domain["Domain services"]
  node_models["Domain models<br/>[models.py]"]
  node_client_service["Client management<br/>[client_service.py]"]
  node_service_service["Service management<br/>[service_service.py]"]
  node_appointment_service["Appointment lifecycle"]
  node_registration_service["Invitation registration"]
end

subgraph group_persistence["Persistence"]
  node_db_contracts["Database contracts<br/>[base.py]"]
  node_memory_db[("Memory storage<br/>[memory.py]")]
  node_supabase_db["Supabase adapters<br/>[supabase.py]"]
  node_registration_repo["Invitation repository"]
end

subgraph group_calendar["Calendar integration"]
  node_calendar_contract["Calendar contract<br/>[base.py]"]
  node_mock_calendar["Mock calendar<br/>[google_mock.py]"]
  node_google_calendar["Google Calendar adapter<br/>[google.py]"]
end

node_admin(("API caller"))
node_supabase_service[("Supabase platform")]
node_google(("Google services"))

node_admin -->|"calls routes"| node_client_api
node_admin -->|"calls routes"| node_appointment_api
node_admin -->|"calls routes"| node_registration_api
node_app -->|"registers routes"| node_client_api
node_app -->|"registers routes"| node_appointment_api
node_app -->|"registers routes"| node_registration_api
node_app -->|"configures"| node_client_service
node_app -->|"configures"| node_appointment_service
node_app -->|"configures"| node_registration_service
node_app -->|"configures"| node_service_service
node_app -->|"selects backend"| node_memory_db
node_app -->|"selects backend"| node_supabase_db
node_app -->|"selects backend"| node_mock_calendar
node_app -->|"selects backend"| node_google_calendar
node_app -->|"registers routes"| node_google_api
node_client_api -->|"delegates to"| node_client_service
node_appointment_api -->|"delegates to"| node_appointment_service
node_appointment_api -->|"delegates to"| node_service_service
node_registration_api -->|"delegates to"| node_registration_service
node_google_api -->|"uses OAuth"| node_google_calendar
node_google_api -->|"uses security"| node_security
node_client_service -->|"reads and writes"| node_memory_db
node_client_service -->|"reads and writes"| node_supabase_db
node_service_service -.->|"reads and writes"| node_memory_db
node_service_service -->|"reads and writes"| node_supabase_db
node_appointment_service -->|"reads and writes"| node_memory_db
node_appointment_service -->|"reads and writes"| node_supabase_db
node_appointment_service -->|"syncs events"| node_calendar_contract
node_appointment_service -.->|"resolves service"| node_service_service
node_registration_service -->|"stores invitations"| node_registration_repo
node_registration_service -->|"registers client"| node_client_service
node_registration_repo -->|"uses REST and RPC"| node_supabase_service
node_supabase_db -.->|"accesses tables"| node_supabase_service
node_memory_db -->|"implements contracts"| node_db_contracts
node_supabase_db -->|"implements contracts"| node_db_contracts
node_google_calendar -->|"implements contract"| node_calendar_contract
node_mock_calendar -->|"implements contract"| node_calendar_contract
node_google_calendar -.->|"syncs events"| node_google
node_google -->|"returns OAuth callback"| node_google_api
node_client_api -->|"validates data"| node_models
node_appointment_api -->|"validates data"| node_models
node_registration_api -->|"validates data"| node_models
node_appointment_service -->|"builds appointments"| node_models
node_client_service -->|"builds clients"| node_models
node_service_service -->|"builds services"| node_models

click node_app "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/main.py"
click node_client_api "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/api/client_endpoints.py"
click node_appointment_api "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/api/endpoints.py"
click node_registration_api "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/api/registration_endpoints.py"
click node_google_api "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/api/google_endpoints.py"
click node_security "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/api/security.py"
click node_models "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/domain/models.py"
click node_client_service "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/services/client_service.py"
click node_service_service "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/services/service_service.py"
click node_appointment_service "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/services/appointment_service.py"
click node_registration_service "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/services/registration_service.py"
click node_db_contracts "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/infrastructure/database/base.py"
click node_memory_db "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/infrastructure/database/memory.py"
click node_supabase_db "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/infrastructure/database/supabase.py"
click node_registration_repo "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/infrastructure/database/registration_repository.py"
click node_calendar_contract "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/infrastructure/calendar/base.py"
click node_mock_calendar "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/infrastructure/calendar/google_mock.py"
click node_google_calendar "https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/infrastructure/calendar/google.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_app,node_client_api,node_appointment_api,node_registration_api,node_google_api,node_security toneBlue
class node_models,node_client_service,node_service_service,node_appointment_service,node_registration_service,node_supabase_service toneAmber
class node_db_contracts,node_memory_db,node_supabase_db,node_registration_repo,node_admin toneMint
class node_calendar_contract,node_mock_calendar,node_google_calendar toneRose
class node_google toneIndigo
```

## Components

### API and setup

- [Application wiring](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/main.py): `main.py`
- [Client routes](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/api/client_endpoints.py): `app/api/client_endpoints.py`
- [Appointment and service routes](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/api/endpoints.py): `app/api/endpoints.py`
- [Registration routes](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/api/registration_endpoints.py): `app/api/registration_endpoints.py`
- [Google OAuth routes](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/api/google_endpoints.py): `app/api/google_endpoints.py`
- [Admin security](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/api/security.py): `app/api/security.py`

### Domain services

- [Domain models](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/domain/models.py): `app/domain/models.py`
- [Client management](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/services/client_service.py): `app/services/client_service.py`
- [Service management](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/services/service_service.py): `app/services/service_service.py`
- [Appointment lifecycle](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/services/appointment_service.py): `app/services/appointment_service.py`
- [Invitation registration](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/services/registration_service.py): `app/services/registration_service.py`

### Persistence

- [Database contracts](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/infrastructure/database/base.py): `app/infrastructure/database/base.py`
- [Memory storage](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/infrastructure/database/memory.py): `app/infrastructure/database/memory.py`
- [Supabase adapters](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/infrastructure/database/supabase.py): `app/infrastructure/database/supabase.py`
- [Invitation repository](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/infrastructure/database/registration_repository.py): `app/infrastructure/database/registration_repository.py`

### Calendar integration

- [Calendar contract](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/infrastructure/calendar/base.py): `app/infrastructure/calendar/base.py`
- [Mock calendar](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/infrastructure/calendar/google_mock.py): `app/infrastructure/calendar/google_mock.py`
- [Google Calendar adapter](https://github.com/brunomygueldotcom/automatize-python-nailflows/blob/main/app/infrastructure/calendar/google.py): `app/infrastructure/calendar/google.py`

### Other components

- **API caller**
- **Supabase platform**
- **Google services**

## Connections

- API caller → Client routes: calls routes (evidence: `README.md`)
- API caller → Appointment and service routes: calls routes (evidence: `README.md`)
- API caller → Registration routes: calls routes (evidence: `README.md`)
- Application wiring → Client routes: registers routes (evidence: `main.py`)
- Application wiring → Appointment and service routes: registers routes (evidence: `main.py`)
- Application wiring → Registration routes: registers routes (evidence: `main.py`)
- Application wiring → Client management: configures (evidence: `main.py`)
- Application wiring → Appointment lifecycle: configures (evidence: `main.py`)
- Application wiring → Invitation registration: configures (evidence: `main.py`)
- Application wiring → Service management: configures (evidence: `main.py`)
- Application wiring → Memory storage: selects backend (evidence: `main.py`)
- Application wiring → Supabase adapters: selects backend (evidence: `main.py`)
- Application wiring → Mock calendar: selects backend (evidence: `main.py`)
- Application wiring → Google Calendar adapter: selects backend (evidence: `main.py`)
- Application wiring → Google OAuth routes: registers routes (evidence: `main.py`)
- Client routes → Client management: delegates to (evidence: `app/api/client_endpoints.py`)
- Appointment and service routes → Appointment lifecycle: delegates to (evidence: `app/api/endpoints.py`)
- Appointment and service routes → Service management: delegates to (evidence: `app/api/endpoints.py`)
- Registration routes → Invitation registration: delegates to (evidence: `app/api/registration_endpoints.py`)
- Google OAuth routes → Google Calendar adapter: uses OAuth (evidence: `app/api/google_endpoints.py`)
- Google OAuth routes → Admin security: uses security (evidence: `app/api/google_endpoints.py`)
- Client management → Memory storage: reads and writes (evidence: `app/services/client_service.py`)
- Client management → Supabase adapters: reads and writes (evidence: `app/services/client_service.py`)
- Service management → Memory storage: reads and writes
- Service management → Supabase adapters: reads and writes (evidence: `app/services/service_service.py`)
- Appointment lifecycle → Memory storage: reads and writes (evidence: `app/services/appointment_service.py`)
- Appointment lifecycle → Supabase adapters: reads and writes (evidence: `app/services/appointment_service.py`)
- Appointment lifecycle → Calendar contract: syncs events (evidence: `app/services/appointment_service.py`)
- Appointment lifecycle → Service management: resolves service
- Invitation registration → Invitation repository: stores invitations (evidence: `app/services/registration_service.py`)
- Invitation registration → Client management: registers client (evidence: `app/services/registration_service.py`)
- Invitation repository → Supabase platform: uses REST and RPC (evidence: `app/infrastructure/database/registration_repository.py`)
- Supabase adapters → Supabase platform: accesses tables
- Memory storage → Database contracts: implements contracts (evidence: `app/infrastructure/database/memory.py`)
- Supabase adapters → Database contracts: implements contracts (evidence: `app/infrastructure/database/supabase.py`)
- Google Calendar adapter → Calendar contract: implements contract (evidence: `app/infrastructure/calendar/google.py`)
- Mock calendar → Calendar contract: implements contract (evidence: `app/infrastructure/calendar/google_mock.py`)
- Google Calendar adapter → Google services: syncs events
- Google services → Google OAuth routes: returns OAuth callback (evidence: `README.md`)
- Client routes → Domain models: validates data (evidence: `app/api/client_endpoints.py`)
- Appointment and service routes → Domain models: validates data (evidence: `app/api/endpoints.py`)
- Registration routes → Domain models: validates data (evidence: `app/api/registration_endpoints.py`)
- Appointment lifecycle → Domain models: builds appointments (evidence: `app/services/appointment_service.py`)
- Client management → Domain models: builds clients (evidence: `app/services/client_service.py`)
- Service management → Domain models: builds services (evidence: `app/services/service_service.py`)