# yetone/shorturl architecture

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

- Interactive diagram: https://gitdiagram.com/yetone/shorturl
- Repository: https://github.com/yetone/shorturl

## Overview

##### Main Components
- Backend Service: Built using FastAPI; located in the “backend” directory. It handles API endpoints, business logic (URL creation, redirection, analytics tracking), authentication via JWT, and database interactions using SQLAlchemy. Note the presence of migration scripts (via Alembic) which manage the database schema.
- Frontend Application: A React application developed in TypeScript; located in the “frontend” directory. It provides the user interface for URL management, registration/login, and displays analytics using libraries like Recharts.
- Database: While SQLite is the default configuration (with options for PostgreSQL/MySQL), it’s central to storing URL mappings, user data, and analytics data.
- External Services / Data: The “geodata” directory containing the GeoLite2-City.mmdb suggests that the backend might include geolocation features to enhance analytics by mapping IP addresses to geographical data.
- Docker Setup: The Dockerfile and associated ignore files indicate containerization for deployment.

##### Relationships and Interactions
- User Interaction Flow: Users interact with the Frontend (React app) to create, manage, and view shortened URLs.
- API Layer: The Frontend communicates with the Backend via REST endpoints (documented in Swagger and ReDoc). This layer handles authentication, URL redirection, and analytics data submission.
- Database Communication: The Backend uses SQLAlchemy to interact with the database (whether SQLite or other SQL databases), and Alembic runs migrations to update the schema.
- Authentication Flow: Secure registration and login are managed by JWT where tokens are issued upon successful authentication.
- Analytics & Geolocation: When a short URL is accessed, the request is processed by the Backend, which tracks click data and employs the GeoLite2 database to resolve geolocation.
- Developer Operations: Docker and configuration files guide deployment and environment setup.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project is segmented into a clear Frontend/Backend separation.
- RESTful API Design: The backend design follows REST principles, providing endpoints for URL creation, redirection, and analytics.
- MVC-like Separation within Backend: Even if not explicitly an MVC framework, the file organization into models, schemas, and routers mirrors this pattern.
- Containerization: Use of Docker indicates an isolated, portable, and consistent runtime environment.

##### Technologies & Frameworks
- Backend: FastAPI, SQLAlchemy, JWT, Alembic for migrations, Python environment configuration files (.env).
- Frontend: React, TypeScript, Tailwind CSS, React Query (for data fetching), Recharts (for visualizing analytics).
- Database: SQLite by default with adaptability for other SQL databases.
- Additional Data Resource: GeoLite2 for geolocation.
- Containerization: Docker for deploying the application.

## Diagram (Mermaid)

```mermaid
graph TD
    Title["System Architecture for Short URL Service"]:::title

    U["User (Browser)"]:::user
    F["React Application (Frontend)"]:::frontend
    B["FastAPI Server (Backend)"]:::backend
    A["API Endpoints & Business Logic"]:::api
    D["Database Interactions & Migrations (SQL Database)"]:::database
    G["Analytics & Geolocation (GeoLite2)"]:::analytics
    DC["Docker Container (Deployment)"]:::docker

    %% Flow Connections
    U -->|"Requests"| F
    F -->|"API_Calls"| B
    B -->|"Handles"| A
    A -->|"DataOperations"| D
    A -->|"TracksClicks"| G
    DC -->|"Deploys"| F
    DC -->|"Deploys"| B

    %% Click Events for Backend Service
    click B "https://github.com/yetone/shorturl/tree/main/backend/"
    click B "https://github.com/yetone/shorturl/tree/main/backend/app/"

    %% Click Events for API Endpoints & Business Logic
    click A "https://github.com/yetone/shorturl/tree/main/backend/app/routers/"
    click A "https://github.com/yetone/shorturl/blob/main/backend/app/auth.py"

    %% Click Events for Database Interactions & Migrations
    click D "https://github.com/yetone/shorturl/blob/main/backend/app/database.py"
    click D "https://github.com/yetone/shorturl/tree/main/backend/app/models/"
    click D "https://github.com/yetone/shorturl/tree/main/backend/migrations/"

    %% Click Events for Frontend Application
    click F "https://github.com/yetone/shorturl/tree/main/frontend/"
    click F "https://github.com/yetone/shorturl/tree/main/frontend/src/"

    %% Click Event for Analytics & Geolocation
    click G "https://github.com/yetone/shorturl/blob/main/geodata/GeoLite2-City.mmdb"

    %% Click Events for Containerization
    click DC "https://github.com/yetone/shorturl/tree/main/Dockerfile"
    click DC "https://github.com/yetone/shorturl/blob/main/.dockerignore"

    %% Styling Classes
    classDef title fill:#ffffff,stroke:#000000,stroke-width:2px,font-size:16px,font-weight:bold;
    classDef user fill:#FFEB99,stroke:#B58900,stroke-width:2px;
    classDef frontend fill:#AEDFF7,stroke:#2A7F9D,stroke-width:2px;
    classDef backend fill:#F7A1A1,stroke:#D64545,stroke-width:2px;
    classDef api fill:#FAD4D4,stroke:#D64545,stroke-width:2px;
    classDef database fill:#D0E6A5,stroke:#7F9A65,stroke-width:2px;
    classDef analytics fill:#D3B8FF,stroke:#8A2BE2,stroke-width:2px;
    classDef docker fill:#B8E0D2,stroke:#2E8B57,stroke-width:2px;
```
