# geam-dev/qr_challenge architecture

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

- Interactive diagram: https://gitdiagram.com/geam-dev/qr_challenge
- Repository: https://github.com/geam-dev/qr_challenge

## Overview

##### Main Components

A. External Components:
- Client Applications (Mobile/Web)
- IPInfo.io Service (External API)
- Database (PostgreSQL, indicated by alembic usage)

B. Internal Components (Following the 3-Layer Architecture):

##### Service Layer
- Auth Service
- QR Code Service
- Client Info Service
- CRUD Service

##### Persistence Layer
- Database Models
- Database Connection
- Alembic Migrations

**[External Clients]**
- ↓
**[API Gateway/FastAPI]**
- ↓
**[Presentation Layer]**
- ↓
**[Service Layer]**
- ↓
**[Persistence Layer]**
- ↓
**[Database]**

##### Key Flows

A. QR Code Generation Flow:
**Client → Auth Endpoint → Auth Service → DB**
**Client → QR Endpoint → QR Service → DB**

B. QR Code Scanning Flow:
**Client → QR Endpoint → QR Service → Client Info Service → IPInfo.io → DB**

##### Important Elements

a. Authentication Components:
- JWT Token Flow
- Auth Middleware

b. Data Flows:
- QR Code Generation
- QR Code Scanning
- Analytics Collection

c. External Integrations:
- IPInfo.io Service Connection
- Database Connection

##### Additional Details

Technical specifications in notes or legends:
- FastAPI Framework
- Alembic for Migrations
- JWT Authentication
- PostgreSQL Database
- Environment Configuration

##### Specific Implementation Notes

- Clear separation of the three architectural layers
- The role of services in handling business logic
- The flow of data from QR code generation to analytics collection
- Security middleware for protected endpoints
- Integration with external services for IP information
- Database schema migrations with Alembic

Remember to:
- Keep the main flows clear and visible
- Use consistent styling for similar components
- Notes for important configuration details
- Both synchronous and asynchronous operations where applicable

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Layer
    subgraph External
        Client[Client Applications]:::client
        IPInfo[IPInfo.io Service]:::external
    end

    %% API Gateway Layer
    subgraph Gateway
        FastAPI[FastAPI Application]:::gateway
        click FastAPI "https://github.com/geam-dev/qr_challenge/blob/main/app/src/main.py"
    end

    %% Presentation Layer
    subgraph Presentation
        AuthEndpoints[Auth Endpoints]:::endpoint
        QREndpoints[QR Code Endpoints]:::endpoint
        click AuthEndpoints "https://github.com/geam-dev/qr_challenge/blob/main/app/src/endpoints/auth.py"
        click QREndpoints "https://github.com/geam-dev/qr_challenge/blob/main/app/src/endpoints/qr_codes.py"
    end

    %% Service Layer
    subgraph Services
        AuthService[Auth Service]:::service
        QRService[QR Code Service]:::service
        ClientInfoService[Client Info Service]:::service
        CRUDService[CRUD Service]:::service
        click AuthService "https://github.com/geam-dev/qr_challenge/blob/main/app/src/services/auth.py"
        click QRService "https://github.com/geam-dev/qr_challenge/blob/main/app/src/services/qr_codes.py"
        click ClientInfoService "https://github.com/geam-dev/qr_challenge/blob/main/app/src/services/client_info.py"
        click CRUDService "https://github.com/geam-dev/qr_challenge/blob/main/app/src/services/crud.py"
    end

    %% Persistence Layer
    subgraph Persistence
        Models[Database Models]:::persistence
        DBConn[Database Connection]:::persistence
        Migrations[Database Migrations]:::persistence
        Schemas[Data Schemas]:::persistence
        click Models "https://github.com/geam-dev/qr_challenge/blob/main/app/src/models.py"
        click DBConn "https://github.com/geam-dev/qr_challenge/blob/main/app/src/db.py"
        click Migrations "https://github.com/geam-dev/qr_challenge/tree/main/app/alembic"
        click Schemas "https://github.com/geam-dev/qr_challenge/blob/main/app/src/schemas.py"
    end

    %% Database Layer
    Database[(PostgreSQL)]:::database

    %% Cross-cutting Concerns
    ExceptionHandler[Exception Handler]:::support
    EnvConfig[Environment Config]:::support
    click ExceptionHandler "https://github.com/geam-dev/qr_challenge/blob/main/app/src/exceptions.py"
    click EnvConfig "https://github.com/geam-dev/qr_challenge/blob/main/app/template.env"

    %% Relationships
    Client --> FastAPI
    FastAPI --> AuthEndpoints
    FastAPI --> QREndpoints
    AuthEndpoints --> AuthService
    QREndpoints --> QRService
    QRService --> ClientInfoService
    ClientInfoService --> IPInfo
    AuthService --> CRUDService
    QRService --> CRUDService
    CRUDService --> Models
    Models --> DBConn
    DBConn --> Database
    Migrations --> Database

    %% Styles
    classDef client fill:#2196F3,stroke:#1565C0,color:white
    classDef external fill:#90A4AE,stroke:#546E7A,color:white
    classDef gateway fill:#4CAF50,stroke:#2E7D32,color:white
    classDef endpoint fill:#8BC34A,stroke:#558B2F,color:white
    classDef service fill:#FFC107,stroke:#FFA000,color:black
    classDef persistence fill:#FF9800,stroke:#F57C00,color:white
    classDef database fill:#795548,stroke:#5D4037,color:white
    classDef support fill:#9C27B0,stroke:#7B1FA2,color:white
```
