# robsonfe/iponto-api architecture

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

- Interactive diagram: https://gitdiagram.com/robsonfe/iponto-api
- Repository: https://github.com/robsonfe/iponto-api

## Overview

##### Project type and purpose
- This is a backend-only RESTful API built with Python, Django and Django REST Framework.
- Purpose: manage employee time-punch records by company, produce monthly reports, and enrich data via an external AI service (DeepSeek).

##### File structure
- Top-level:
- core/ – Django project settings, URL routing, ASGI/WSGI
- api/ – Django app containing models, serializers, views, permissions, swagger mixins, migrations
- docs/ – documentation files
- manage.py, requirements.txt, .env.example
- api/ substructure follows logical modules:
- model/ – domain models (Company, Employee, CustomUser)
- serializers/ – translate Django models to/from JSON
- view/ – view classes for each resource (authentication, company, employee, transferer)
- permissions/ – custom DRF permissions
- swagger/ – mixins to auto-generate API docs
- utils/ – support modules (e.g., allowed_tags)

##### README insights
- Stack: Python, Django, DRF, PostgreSQL, external DeepSeek AI.
- Key use cases: user signup/login, CRUD on time entries, monthly report generation, real-time dashboards with AI-powered metrics.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    Client["Web Dashboard (Client)"]:::client

    %% API Entry Points
    subgraph "Django REST API Server"
        direction TB

        %% Routing
        API_Routes["URL Routing"]:::internal
        click API_Routes "https://github.com/robsonfe/iponto-api/blob/main/api/urls.py"
        click API_Routes "https://github.com/robsonfe/iponto-api/blob/main/core/urls.py"

        %% View Layer
        subgraph "Views"
            direction TB
            AuthView["AuthenticationView"]:::internal
            click AuthView "https://github.com/robsonfe/iponto-api/blob/main/api/view/authentication_view.py"
            CompanyView["CompanyView"]:::internal
            click CompanyView "https://github.com/robsonfe/iponto-api/blob/main/api/view/company_view.py"
            EmployeeView["EmployeeView"]:::internal
            click EmployeeView "https://github.com/robsonfe/iponto-api/blob/main/api/view/employee_view.py"
            EmployeeTransfererView["EmployeeTransfererView"]:::internal
            click EmployeeTransfererView "https://github.com/robsonfe/iponto-api/blob/main/api/view/employee_transferer_view.py"
            UserView["UserView"]:::internal
            click UserView "https://github.com/robsonfe/iponto-api/blob/main/api/view/user_view.py"
        end

        %% Serializer Layer
        subgraph "Serializers"
            direction TB
            AuthSerializer["AuthenticationSerializer"]:::internal
            click AuthSerializer "https://github.com/robsonfe/iponto-api/blob/main/api/serializers/authentication_serializer.py"
            CompanySerializer["CompanySerializer"]:::internal
            click CompanySerializer "https://github.com/robsonfe/iponto-api/blob/main/api/serializers/company_serializer.py"
            EmployeeSerializer["EmployeeSerializer"]:::internal
            click EmployeeSerializer "https://github.com/robsonfe/iponto-api/blob/main/api/serializers/employee_serializer.py"
            EmployeeTransfererSerializer["EmployeeTransfererSerializer"]:::internal
            click EmployeeTransfererSerializer "https://github.com/robsonfe/iponto-api/blob/main/api/serializers/employee_transferer_serializer.py"
            CustomUserSerializer["CustomUserSerializer"]:::internal
            click CustomUserSerializer "https://github.com/robsonfe/iponto-api/blob/main/api/serializers/customuser_serializer.py"
        end

        %% Permissions
        Permissions["Permissions"]:::internal
        click Permissions "https://github.com/robsonfe/iponto-api/blob/main/api/permissions/permissions.py"

        %% Swagger Mixins
        subgraph "Swagger Mixins"
            direction TB
            AuthSwagger["Auth Swagger Mixin"]:::internal
            click AuthSwagger "https://github.com/robsonfe/iponto-api/blob/main/api/swagger/authentication_mixin_swagger.py"
            CompanySwagger["Company Swagger Mixin"]:::internal
            click CompanySwagger "https://github.com/robsonfe/iponto-api/blob/main/api/swagger/company_mixin_swagger.py"
            EmployeeSwagger["Employee Swagger Mixin"]:::internal
            click EmployeeSwagger "https://github.com/robsonfe/iponto-api/blob/main/api/swagger/employee_mixin_swagger.py"
            UserSwagger["User Swagger Mixin"]:::internal
            click UserSwagger "https://github.com/robsonfe/iponto-api/blob/main/api/swagger/user_mixin_swagger.py"
        end

        %% Utility Components
        AllowedTags["allowed_tags Utility"]:::internal
        click AllowedTags "https://github.com/robsonfe/iponto-api/blob/main/api/utils/allowed_tags.py"

        %% Model Layer
        subgraph "Models"
            direction TB
            CompanyModel["Company Model"]:::internal
            click CompanyModel "https://github.com/robsonfe/iponto-api/blob/main/api/model/company_model.py"
            EmployeeModel["Employee Model"]:::internal
            click EmployeeModel "https://github.com/robsonfe/iponto-api/blob/main/api/model/employee_model.py"
            CustomUserModel["CustomUser Model"]:::internal
            click CustomUserModel "https://github.com/robsonfe/iponto-api/blob/main/api/model/Customuser.py"
        end

        %% Reporting & Metrics
        ReportingService["ReportingService"]:::internal

        %% Async Processing
        subgraph "Async Processing"
            direction TB
            Broker["Message Broker"]:::internal
            AsyncQueue["Celery Worker/Queue"]:::internal
        end

        %% Core Config
        CoreSettings["Django Core (settings/asgi/wsgi)"]:::internal
        click CoreSettings "https://github.com/robsonfe/iponto-api/blob/main/core/settings.py"
        click CoreSettings "https://github.com/robsonfe/iponto-api/blob/main/core/asgi.py"
        click CoreSettings "https://github.com/robsonfe/iponto-api/blob/main/core/wsgi.py"
    end

    %% Database
    Postgres["PostgreSQL Database"]:::db

    %% External Service
    DeepSeek["DeepSeek AI Service"]:::external

    %% Data Flows
    Client -->|HTTP/HTTPS| API_Routes
    API_Routes --> AuthView
    API_Routes --> CompanyView
    API_Routes --> EmployeeView
    API_Routes --> EmployeeTransfererView
    API_Routes --> UserView

    %% View interactions
    AuthView -->|uses| AuthSerializer
    CompanyView -->|uses| CompanySerializer
    EmployeeView -->|uses| EmployeeSerializer
    EmployeeTransfererView -->|uses| EmployeeTransfererSerializer
    UserView -->|uses| CustomUserSerializer

    AuthView -->|checks| Permissions
    CompanyView -->|checks| Permissions
    EmployeeView -->|checks| Permissions
    EmployeeTransfererView -->|checks| Permissions
    UserView -->|checks| Permissions

    AuthView -->|docs| AuthSwagger
    CompanyView -->|docs| CompanySwagger
    EmployeeView -->|docs| EmployeeSwagger
    UserView -->|docs| UserSwagger

    AuthView -->|calls| CoreSettings
    CompanyView -->|calls| CoreSettings
    EmployeeView -->|calls| CoreSettings
    EmployeeTransfererView -->|calls| CoreSettings
    UserView -->|calls| CoreSettings

    %% Serializer to Models
    AuthSerializer -->|maps| CustomUserModel
    CompanySerializer -->|maps| CompanyModel
    EmployeeSerializer -->|maps| EmployeeModel
    EmployeeTransfererSerializer -->|maps| EmployeeModel
    CustomUserSerializer -->|maps| CustomUserModel

    %% Models to DB
    CompanyModel -->|SQL| Postgres
    EmployeeModel -->|SQL| Postgres
    CustomUserModel -->|SQL| Postgres

    %% Utils usage
    EmployeeView -->|uses| AllowedTags
    CompanyView -->|uses| AllowedTags

    %% Reporting flow
    EmployeeView -->|requests report| ReportingService
    CompanyView -->|requests report| ReportingService
    ReportingService -->|enqueue| Broker
    Broker -->|process| AsyncQueue
    AsyncQueue -->|writes| Postgres

    %% External AI integration
    ReportingService -->|REST API| DeepSeek
    DeepSeek -->|response| ReportingService

    %% Return to Client
    ReportingService -->|returns metrics| Client

    %% Styles
    classDef client fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef internal fill:#cfe2f3,stroke:#036,stroke-width:1px
    classDef external fill:#d9ead3,stroke:#090,stroke-width:1px
    classDef db fill:#bdd7ee,stroke:#115,stroke-width:1px
```
