# gideon-nobbs7/shortly architecture

> Architecture diagram of the GitHub repository gideon-nobbs7/shortly, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gideon-nobbs7/shortly
- Repository: https://github.com/gideon-nobbs7/shortly

## Overview

##### Project Type and Purpose
- The project is a full-stack backend application built with FastAPI. Its purpose is to serve as a link shortener, handling URL shortening operations and managing user-related link data.
- The README and file tree reveal inspirations from Real Python’s tutorial. It includes demo assets, database schemas, and migrations (e.g., Alembic) for managing updates to the database structure.

##### File Structure
- There are top-level artifacts like Dockerfile, docker-compose.yml, and configuration files (e.g., alembic.ini) that indicate containerization and database migration management.
- The “src” directory contains subdirectories:
– routes: Contains API endpoints (admin.py, user.py) which handle client HTTP requests.
– schemas: Defines data models (using Pydantic) for validating requests/responses (e.g., url.py, user.py, user_url.py).
– turtle_link_shortener: Houses core business logic including configuration (config.py), database connections (database.py), data models (models.py), error handling (errors.py), and security (security.py).
– utils: Utility functions for common tasks, including database utilities, QR utilities, and router utilities.
- Alembic files and directories manage database migrations, ensuring that schema changes are trackable and reversible.

##### Components and Their Relationships
- Main Entry Point: The main.py file initializes the FastAPI application and ties components together.
- API Layer: The “routes” directory outlines how external API calls are handled. Specifically, the admin and user endpoints accept and respond to HTTP requests.
- Business Logic Layer: Located inside turtle_link_shortener, this module contains configuration, database management, models, and security functionality. API routes call these functions to process application-specific features.
- Database Layer: Represented by the database.py file, the models in models.py, and the Alembic migrations. These ensure persistent storage of user data and shortened URLs.
- Utility/Helper Layer: The “utils” directory includes helper functions such as establishing or enhancing database operations (database_utils.py), generating QR codes (qr_utils.py), and streamlining route operations (router_utils.py).
- Deployment/Infrastructure Layer: Dockerfile and docker-compose.yml support containerized deployment which can be illustrated as part of the infrastructure that holds the application, along with external assets and potential external services (if any).

##### Architectural Patterns and Technologies
- MVC/Microservice-Like Separation: Although not a strict MVC, the separation of routes (controller layer), schemas (data model or view layer), and turtle_link_shortener (business logic/model layer) is evident.
- Database Migration with Alembic: Highlight the presence of versioned migrations.
- Use of FastAPI: Emphasizes an asynchronous, Python-based web framework for API development.
- Containerization: Involvement of Docker indicates the project is designed for consistent deployment across environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client("External Client"):::client
    APIGateway("API Gateway / Entry Point<br/>(main.py)"):::gateway

    %% API Layer: Routes Subgraph
    subgraph "API Routes"
        AdminRoute("Admin Route<br/>(admin.py)"):::routes
        UserRoute("User Route<br/>(user.py)"):::routes
    end

    %% API Layer: Schemas Subgraph
    subgraph "Data Schemas"
        SchemaURL("Schema: url.py"):::schemas
        SchemaUser("Schema: user.py"):::schemas
        SchemaUserURL("Schema: user_url.py"):::schemas
    end

    %% Business Logic Layer
    subgraph "Business Logic & Core Modules"
        Config("Config<br/>(config.py)"):::business
        Errors("Errors<br/>(errors.py)"):::business
        ModelsBL("Models<br/>(models.py)"):::business
        Security("Security<br/>(security.py)"):::business
    end

    %% Database Layer
    subgraph "Database Layer"
        DB_Database("DB Connection<br/>(database.py)"):::database
        DB_Models("DB Models<br/>(models.py)"):::database
        AlembicVersions("Alembic<br/>(versions/)"):::database
        AlembicIni("Alembic Config<br/>(alembic.ini)"):::database
        AlembicEnv("Alembic Env<br/>(alembic/env.py)"):::database
    end

    %% Utility/Helper Layer
    subgraph "Utility/Helper Layer"
        DBUtils("DB Utils<br/>(database_utils.py)"):::utilities
        QRUtils("QR Utils<br/>(qr_utils.py)"):::utilities
        RouterUtils("Router Utils<br/>(router_utils.py)"):::utilities
        Snowflake("Snowflake<br/>(snowflake.py)"):::utilities
    end

    %% Deployment / Containerization Layer
    subgraph "Deployment / Containerization"
        Dockerfile("Dockerfile"):::deployment
        DockerCompose("docker-compose.yml"):::deployment
        Assets("Assets<br/>(assets)"):::deployment
    end

    %% Connections between layers
    Client --> APIGateway
    APIGateway --> AdminRoute
    APIGateway --> UserRoute
    AdminRoute --> Config
    UserRoute --> Config
    SchemaURL --> Config
    SchemaUser --> Config
    SchemaUserURL --> Config
    Config --> DB_Database
    Config --> DBUtils
    ModelsBL --> DB_Models

    %% Deployment influences overall environment (dotted arrows)
    DockerCompose -.-> APIGateway
    Assets -.-> DB_Database

    %% Class Definitions for colours and styles
    classDef client fill:#FFDDC1,stroke:#E85A4F,stroke-width:2px;
    classDef gateway fill:#C1E1FF,stroke:#1F75FE,stroke-width:2px;
    classDef routes fill:#C1FFC1,stroke:#008000,stroke-width:2px;
    classDef schemas fill:#FFFFC1,stroke:#CCCC00,stroke-width:2px;
    classDef business fill:#FFD1DC,stroke:#FF69B4,stroke-width:2px;
    classDef database fill:#FFE5B4,stroke:#FF8C00,stroke-width:2px;
    classDef utilities fill:#D3D3D3,stroke:#696969,stroke-width:2px;
    classDef deployment fill:#E0E0E0,stroke:#808080,stroke-width:2px;

    %% Click Events for API Gateway & Routes
    click APIGateway "https://github.com/gideon-nobbs7/shortly/blob/main/main.py"
    click AdminRoute "https://github.com/gideon-nobbs7/shortly/blob/main/src/routes/admin.py"
    click UserRoute "https://github.com/gideon-nobbs7/shortly/blob/main/src/routes/user.py"

    %% Click Events for Data Schemas
    click SchemaURL "https://github.com/gideon-nobbs7/shortly/blob/main/src/schemas/url.py"
    click SchemaUser "https://github.com/gideon-nobbs7/shortly/blob/main/src/schemas/user.py"
    click SchemaUserURL "https://github.com/gideon-nobbs7/shortly/blob/main/src/schemas/user_url.py"

    %% Click Events for Business Logic & Core Modules
    click Config "https://github.com/gideon-nobbs7/shortly/blob/main/src/turtle_link_shortener/config.py"
    click Errors "https://github.com/gideon-nobbs7/shortly/blob/main/src/turtle_link_shortener/errors.py"
    click ModelsBL "https://github.com/gideon-nobbs7/shortly/blob/main/src/turtle_link_shortener/models.py"
    click Security "https://github.com/gideon-nobbs7/shortly/blob/main/src/turtle_link_shortener/security.py"

    %% Click Events for Database Layer
    click DB_Database "https://github.com/gideon-nobbs7/shortly/blob/main/src/turtle_link_shortener/database.py"
    click DB_Models "https://github.com/gideon-nobbs7/shortly/blob/main/src/turtle_link_shortener/models.py"
    click AlembicVersions "https://github.com/gideon-nobbs7/shortly/tree/main/alembic/versions/"
    click AlembicIni "https://github.com/gideon-nobbs7/shortly/blob/main/alembic.ini"
    click AlembicEnv "https://github.com/gideon-nobbs7/shortly/blob/main/alembic/env.py"

    %% Click Events for Utility/Helper Layer
    click DBUtils "https://github.com/gideon-nobbs7/shortly/blob/main/src/utils/database_utils.py"
    click QRUtils "https://github.com/gideon-nobbs7/shortly/blob/main/src/utils/qr_utils.py"
    click RouterUtils "https://github.com/gideon-nobbs7/shortly/blob/main/src/utils/router_utils.py"
    click Snowflake "https://github.com/gideon-nobbs7/shortly/blob/main/src/utils/snowflake.py"

    %% Click Events for Deployment / Containerization
    click Dockerfile "https://github.com/gideon-nobbs7/shortly/tree/main/Dockerfile"
    click DockerCompose "https://github.com/gideon-nobbs7/shortly/blob/main/docker-compose.yml"
    click Assets "https://github.com/gideon-nobbs7/shortly/tree/main/assets"
```
