# aswan-a/fixconnect architecture

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

- Interactive diagram: https://gitdiagram.com/aswan-a/fixconnect
- Repository: https://github.com/aswan-a/fixconnect

## Overview

##### Project type and purpose
- This is the **frontend** of a full-stack web application (“FixConnect”) built with **React 19**, **TypeScript**, **Vite**, and **Tailwind CSS**.
- Its purpose is to let citizens report local infrastructure issues and professionals browse/resolve them via a responsive UI that consumes a RESTful backend API.

##### File structure
- Top-level directories and files:
- `app/` – Contains all React code, organized via file-based routing (`app/routes/`), global styles (`app/app.css`), shared hooks (`app/hooks/`), and utilities (`app/lib/`).
- `public/` – Static assets (images, favicon).
- Configs: `vite.config.ts`, `tsconfig.json`, `react-router.config.ts`, `config.ts`.
- Workspace & Package: `pnpm-workspace.yaml`, `package.json`, lock files, Prettier/ESLint configs.
- Routing pattern: `app/routes/_layout*.tsx` files define nested layouts and protected routes, indicating an **SPA** with client-side routing.
- Component library: `app/components/ui/` holds reusable UI primitives (buttons, cards, forms) from **shadcn/ui**.

##### README for additional insights
- Confirms tech stack (React, TypeScript, Vite, Tailwind, React Router v7).
- Lists API endpoints and authentication flows (JWT login, token refresh).
- Mentions interactive maps, image uploads (carousel), and professional dashboard.

a. Main components
- **Browser / Frontend SPA**
- UI Layer: React components & layouts
- Routing Layer: React Router (file-based)
- State & Data Layer: Context API + custom hooks (`fetchWithAuth`)
- **Backend API** (external system)
- Auth service (login/register/refresh)
- Issue & Request services (CRUD endpoints)
- **Persistent Storage** (database on backend) – not in this repo but indicate as external.
- **Third-Party Services**
- Geolocation / Maps provider (e.g., Google Maps / Mapbox)
- Cloud storage for image uploads (if used)
b. Relationships & interactions
- The SPA makes HTTP(S) requests to backend endpoints (`VITE_API_URL`) using `fetchWithAuth`.
- JWT tokens flow: login → store access/refresh tokens → attach access token in `Authorization` header → token refresh on expiry.
- UI events (form submissions, map interactions) trigger data fetches and state updates.
c. Architectural patterns & design principles
- **Component-based architecture**: Reusable UI primitives in `app/components/ui/`.
- **File-based routing**: Nested routes with shared layouts (`_layout.tsx`).
- **Hooks & Context** for cross-cutting concerns (auth, global state).
- **Utility-first styling** via Tailwind CSS.
- **Code splitting** courtesy of Vite and dynamic imports.
d. Key technologies & frameworks
- React 19, TypeScript, Vite, React Router v7
- Fetch API for HTTP
- pnpm for workspace management

##### Elements
- **Clear labels** for each subsystem (e.g., “React SPA”, “Auth API”, “Issue API”, “PostgreSQL DB”).
- Blue rectangles for client modules (UI, Routing, Hooks)
- Orange rectangles for external services/APIs
- **Annotations** for technologies (e.g., “Vite HMR”, “Tailwind CSS”, “JWT”).

##### Final advice
- **all layers** without over-complicating: separate into as many logical components as makes the flow clear.
- Be **explicit about contracts** (e.g., “POST /api/auth/login → returns { accessToken, refreshToken }”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client"
        direction TB
        subgraph "UI Layer - Reusable Components"
            direction TB
            AspectRatio["AspectRatio"]:::client
            Badge["Badge"]:::client
            Button["Button"]:::client
            Card["Card"]:::client
            Form["Form"]:::client
        end
        subgraph "UI Layer - App-specific Components"
            direction TB
            UserDropdown["UserDropdown"]:::client
        end
        subgraph "Global Styles"
            AppCSS["app.css"]:::client
        end
        subgraph "Root & Context"
            RootTSX["root.tsx"]:::client
        end
        subgraph "Routing Layer"
            direction TB
            Layout["Main Layout"]:::client
            Home["Home Page"]:::client
            CreateIssue["Create Issue"]:::client
            IssuesList["Issues List/Detail"]:::client
            MyIssues["My Issues"]:::client
            Profile["Profile"]:::client
            Login["Login"]:::client
            ProRegister["Pro Registration"]:::client
            Signup["Signup"]:::client
        end
        subgraph "State & Network Layer"
            FetchAuth["fetchWithAuth"]:::client
            Utils["utils"]:::client
        end
        subgraph "Config & Build"
            RouterConfig["react-router.config.ts"]:::client
            ViteConfig["vite.config.ts"]:::client
            TSConfig["tsconfig.json"]:::client
            AppConfig["config.ts"]:::client
        end
    end

    %% Server Side
    subgraph "Backend API"
        direction TB
        AuthAPI["Auth Service"]:::backend
        IssueAPI["Issue & Request Service"]:::backend
    end

    %% Database
    Database["PostgreSQL"]:::database

    %% External Services
    subgraph "External Services"
        direction TB
        Maps["Maps/Geolocation"]:::external
        Storage["Image Storage"]:::external
    end

    %% Flows
    UserDropdown -->|renders| AspectRatio
    Button -->|used in forms| Form
    Form -->|submits to| FetchAuth
    FetchAuth -->|calls| AuthAPI
    Layout -->|routes to| Home
    Layout -->|routes to| CreateIssue
    Layout -->|routes to| IssuesList
    Layout -->|routes to| MyIssues
    Layout -->|routes to| Profile
    Layout -->|routes to| Login
    Layout -->|routes to| ProRegister
    Layout -->|routes to| Signup
    FetchAuth -->|GET/POST| IssueAPI
    AuthAPI -->|reads/writes| Database
    IssueAPI -->|reads/writes| Database
    IssueAPI -->|uploads| Storage
    CreateIssue -->|selects location| Maps

    %% Click Events
    click AspectRatio "https://github.com/aswan-a/fixconnect/blob/master/app/components/ui/aspect-ratio.tsx"
    click Badge "https://github.com/aswan-a/fixconnect/blob/master/app/components/ui/badge.tsx"
    click Button "https://github.com/aswan-a/fixconnect/blob/master/app/components/ui/button.tsx"
    click Card "https://github.com/aswan-a/fixconnect/blob/master/app/components/ui/card.tsx"
    click Form "https://github.com/aswan-a/fixconnect/blob/master/app/components/ui/form.tsx"
    click UserDropdown "https://github.com/aswan-a/fixconnect/blob/master/app/components/UserDropdown.tsx"
    click AppCSS "https://github.com/aswan-a/fixconnect/blob/master/app/app.css"
    click RootTSX "https://github.com/aswan-a/fixconnect/blob/master/app/root.tsx"
    click Layout "https://github.com/aswan-a/fixconnect/blob/master/app/routes/_layout.tsx"
    click Home "https://github.com/aswan-a/fixconnect/blob/master/app/routes/_layout._index.tsx"
    click CreateIssue "https://github.com/aswan-a/fixconnect/blob/master/app/routes/_layout.createissue.tsx"
    click IssuesList "https://github.com/aswan-a/fixconnect/blob/master/app/routes/_layout.issues.$issueId.tsx"
    click MyIssues "https://github.com/aswan-a/fixconnect/blob/master/app/routes/_layout.my_Issues.tsx"
    click Profile "https://github.com/aswan-a/fixconnect/blob/master/app/routes/_layout.profile.tsx"
    click Login "https://github.com/aswan-a/fixconnect/blob/master/app/routes/login.tsx"
    click ProRegister "https://github.com/aswan-a/fixconnect/blob/master/app/routes/pro-register.tsx"
    click Signup "https://github.com/aswan-a/fixconnect/blob/master/app/routes/signup.tsx"
    click FetchAuth "https://github.com/aswan-a/fixconnect/blob/master/app/hooks/fetchWithAuth.ts"
    click Utils "https://github.com/aswan-a/fixconnect/blob/master/app/lib/utils.ts"
    click RouterConfig "https://github.com/aswan-a/fixconnect/blob/master/react-router.config.ts"
    click ViteConfig "https://github.com/aswan-a/fixconnect/blob/master/vite.config.ts"
    click TSConfig "https://github.com/aswan-a/fixconnect/blob/master/tsconfig.json"
    click AppConfig "https://github.com/aswan-a/fixconnect/blob/master/config.ts"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#FFD8A8,stroke:#d97706,stroke-width:1px
    classDef database fill:#D1FAE5,stroke:#059669,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#E5E7EB,stroke:#6B7280,stroke-width:1px,stroke-dasharray: 5 5
```
