# hack-smiths/portfolia architecture

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

- Interactive diagram: https://gitdiagram.com/hack-smiths/portfolia
- Repository: https://github.com/hack-smiths/portfolia

## Overview

##### Project type and purpose
- This is a full-stack web application called “Portfolia” that lets users import GitHub internship/project repos, parse resume PDFs, enhance content with AI, and build/export a polished portfolio.
- Frontend: React + TypeScript (Vite) with TailwindCSS & ShadCN-style components.
- Backend: FastAPI (Python) with SQLAlchemy + PostgreSQL, integrates with GitHub’s REST API and an LLM service (OpenAI or similar).

##### File structure
- Top-level:
- frontend/ – all React UI code (public assets, pages, reusable UI components, hooks, utils, routing)
- backend/ – Python API (app/main.py, app/api/v1/routes, app/crud, app/schemas)
- requirements.txt, package.json, README.md, .env (GitHub token), venv folder for dependencies
- Backend layers:
- Routes (github.py, project.py) define HTTP endpoints under /api/v1
- CRUD layer encapsulates database operations for GitHub-imported entities
- Schemas define Pydantic models for request/response validation
- main.py wires routes, middleware, DB session, and config
- Frontend architecture:
- Pages under src/pages map to routes (Dashboard, Projects, Achievements, etc.)
- components/ holds both domain components (FileUpload, Navbar, dialogs) and a ui/ design system
- hooks/ for shared logic; utils/ for helper functions; App.tsx mounts React Router

##### README for additional insights
- Tech stack summary confirms API auth via GitHub token in .env, LLM integration pending
- Lists feature set: GitHub import, AI enhancements, PDF upload & parsing, live portfolio preview, PDF export

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (React + TypeScript)" 
        direction TB
        Browser["Browser"]:::external
        subgraph "Entrypoint & Config"
            direction TB
            MainTS["main.tsx"]:::frontend
            HTMLTemplate["index.html"]:::frontend
            AppTS["App.tsx"]:::frontend
            ViteConfig["vite.config.ts"]:::frontend
            TailwindConfig["tailwind.config.ts"]:::frontend
        end
        subgraph "Pages"
            direction TB
            Landing["Landing.tsx"]:::frontend
            Auth["Auth.tsx"]:::frontend
            Dashboard["Dashboard.tsx"]:::frontend
            ProjectsPage["Projects.tsx"]:::frontend
            Achievements["Achievements.tsx"]:::frontend
            Skills["Skills.tsx"]:::frontend
            Profile["Profile.tsx"]:::frontend
            Portfolio["Portfolio.tsx"]:::frontend
            DummyPortfolio["DummyPortfolio.tsx"]:::frontend
            ExportPage["Export.tsx"]:::frontend
            NotFound["NotFound.tsx"]:::frontend
        end
        subgraph "Components & Utilities"
            direction TB
            Navbar["Navbar.tsx"]:::frontend
            FileUpload["FileUpload.tsx"]:::frontend
            ResumeDialog["ResumeUploadDialog.tsx"]:::frontend
            EditAchievement["EditAchievementDialog.tsx"]:::frontend
            AIAssist["AIAssistant.tsx"]:::frontend
            AIEditAssist["AIEditAssistant.tsx"]:::frontend
            subgraph "UI Primitives"
                direction TB
                UIPrimitives["ui/*"]:::frontend
            end
            subgraph "Hooks"
                direction TB
                MobileHook["use-mobile.tsx"]:::frontend
                ToastHook["use-toast.ts"]:::frontend
            end
            Utils["utils.ts"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend (FastAPI + Python)"
        direction TB
        MainPy["main.py"]:::backend
        subgraph "API Routes (/api/v1)"
            direction TB
            GitHubRoute["github.py"]:::backend
            ProjectRoute["project.py"]:::backend
        end
        subgraph "Service & CRUD"
            direction TB
            CRUDLayer["crud/github.py"]:::backend
            LLMModule["LLM Integration"]:::backend
            ParserModule["Resume Parser"]:::backend
        end
        subgraph "Schemas (Pydantic)"
            direction TB
            GitHubSchema["github.py"]:::backend
        end
    end

    %% Data & External
    DB[(PostgreSQL)]:::db
    GitHubAPI["GitHub REST API"]:::external
    OpenAIAPI["OpenAI (LLM)"]:::external
    FileStorage["File Storage"]:::external

    %% Connections
    Browser -->|"loads"| MainTS
    MainTS -->|"imports html"| HTMLTemplate
    MainTS -->|"mounts"| AppTS
    AppTS -->|"routes"| Landing
    AppTS -->|"routes"| Auth
    AppTS -->|"routes"| Dashboard
    AppTS -->|"routes"| ProjectsPage
    AppTS -->|"routes"| Achievements
    AppTS -->|"routes"| Skills
    AppTS -->|"routes"| Profile
    AppTS -->|"routes"| Portfolio
    AppTS -->|"routes"| DummyPortfolio
    AppTS -->|"routes"| ExportPage
    AppTS -->|"routes"| NotFound
    AppTS -->|"uses"| Navbar
    AppTS -->|"uses"| FileUpload
    AppTS -->|"uses"| ResumeDialog
    AppTS -->|"uses"| EditAchievement
    AppTS -->|"uses"| AIAssist
    AppTS -->|"uses"| AIEditAssist
    AppTS -->|"uses"| Utils
    AppTS -->|"uses"| MobileHook
    AppTS -->|"uses"| ToastHook

    Browser -->|"API calls"| MainPy
    MainPy -->|"routes to"| GitHubRoute
    MainPy -->|"routes to"| ProjectRoute
    GitHubRoute -->|"calls"| CRUDLayer
    ProjectRoute -->|"calls"| CRUDLayer
    CRUDLayer -->|"reads/writes"| DB
    GitHubRoute -->|"fetch repo"| GitHubAPI
    CRUDLayer -->|"invoke"| LLMModule
    LLMModule -->|"send text"| OpenAIAPI
    ParserModule -->|"process pdf"| FileStorage
    MainPy -->|"serves files"| FileStorage

    %% Click Events
    click MainTS "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/main.tsx"
    click HTMLTemplate "https://github.com/hack-smiths/portfolia/blob/main/frontend/index.html"
    click AppTS "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/App.tsx"
    click ViteConfig "https://github.com/hack-smiths/portfolia/blob/main/frontend/vite.config.ts"
    click TailwindConfig "https://github.com/hack-smiths/portfolia/blob/main/frontend/tailwind.config.ts"
    click Landing "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/pages/Landing.tsx"
    click Auth "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/pages/Auth.tsx"
    click Dashboard "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/pages/Dashboard.tsx"
    click ProjectsPage "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/pages/Projects.tsx"
    click Achievements "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/pages/Achievements.tsx"
    click Skills "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/pages/Skills.tsx"
    click Profile "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/pages/Profile.tsx"
    click Portfolio "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/pages/Portfolio.tsx"
    click DummyPortfolio "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/pages/DummyPortfolio.tsx"
    click ExportPage "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/pages/Export.tsx"
    click NotFound "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/pages/NotFound.tsx"
    click Navbar "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/components/Navbar.tsx"
    click FileUpload "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/components/FileUpload.tsx"
    click ResumeDialog "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/components/ResumeUploadDialog.tsx"
    click EditAchievement "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/components/EditAchievementDialog.tsx"
    click AIAssist "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/components/AIAssistant.tsx"
    click AIEditAssist "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/components/AIEditAssistant.tsx"
    click UIPrimitives "https://github.com/hack-smiths/portfolia/tree/main/frontend/src/components/ui"
    click MobileHook "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/hooks/use-mobile.tsx"
    click ToastHook "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/hooks/use-toast.ts"
    click Utils "https://github.com/hack-smiths/portfolia/blob/main/frontend/src/lib/utils.ts"
    click MainPy "https://github.com/hack-smiths/portfolia/blob/main/backend/app/main.py"
    click GitHubRoute "https://github.com/hack-smiths/portfolia/blob/main/backend/app/api/v1/routes/github.py"
    click ProjectRoute "https://github.com/hack-smiths/portfolia/blob/main/backend/app/api/v1/routes/project.py"
    click CRUDLayer "https://github.com/hack-smiths/portfolia/blob/main/backend/app/crud/github.py"
    click GitHubSchema "https://github.com/hack-smiths/portfolia/blob/main/backend/app/schemas/github.py"
    click DB "https://github.com/hack-smiths/portfolia/blob/main/requirements.txt"
    click OpenAIAPI "https://github.com/hack-smiths/portfolia/blob/main/.env"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#87CEFA,stroke:#000,stroke-width:1px
    classDef db fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
