# ht1makcv5-create/portfolio architecture

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

- Interactive diagram: https://gitdiagram.com/ht1makcv5-create/portfolio
- Repository: https://github.com/ht1makcv5-create/portfolio

## Overview

#### Purpose and Workspace Shape
This is a pnpm TypeScript monorepo for a portfolio/contact-request system: a Vite/React portfolio frontend, a Node API server, shared OpenAPI-derived clients/validation, and a Drizzle database layer. The active application artifacts appear to be under `artifacts/boohx` and `artifacts/api-server`; `artifacts/portfolio-site` and `artifacts/mockup-sandbox` are separate frontend artifacts/snapshots.

Key workspace roots: `package.json`, `pnpm-workspace.yaml`, `tsconfig.base.json`.

#### Frontend Application
The primary frontend is a Vite React single-page portfolio application. Browser bootstrapping flows from `main.tsx` into `App.tsx`, with the portfolio page and visual components rendered from there.

Paths:
- `artifacts/boohx/src/main.tsx`
- `artifacts/boohx/src/App.tsx`
- `artifacts/boohx/src/pages/portfolio.tsx`

It has a GitHub Pages-oriented Vite configuration in addition to its standard Vite config:
- `artifacts/boohx/vite.config.ts`
- `artifacts/boohx/vite.config.ghpages.ts`

#### HTTP API Service
The backend is a standalone TypeScript API server, with process startup separated from application composition. Route registration is centralized, then delegated by concern: health checks, incoming portfolio/contact requests, visitor recording, and admin operations.

Paths:
- `artifacts/api-server/src/index.ts`
- `artifacts/api-server/src/app.ts`
- `artifacts/api-server/src/routes/index.ts`

Primary route boundaries:
- `artifacts/api-server/src/routes/requests.ts`
- `artifacts/api-server/src/routes/visits.ts`
- `artifacts/api-server/src/routes/admin.ts`
- `artifacts/api-server/src/routes/health.ts`

#### Request, Analytics, and Admin Flow
Public clients submit request records and visit events to the API. The API persists these through the shared database package. Admin endpoints expose operational access to requests/dashboard data and use a dedicated admin-session implementation rather than treating public requests as authenticated admin traffic.

Paths:
- `lib/db/src/schema/requests.ts`
- `lib/db/src/schema/visits.ts`
- `artifacts/api-server/src/lib/admin-session.ts`

The OpenAPI contract names the core domain types: requests, request updates/statuses, visits, dashboard data, admin sessions, and Telegram login/bot structures. This contract is the intended API boundary between UI and backend:
- `lib/api-spec/openapi.yaml`
- `lib/api-zod/src/generated/api.ts`

#### Shared Contract and Persistence Layer
`lib/api-spec` is the source API specification; generated Zod types provide runtime validation/type sharing, while the React client package provides generated API calls and a customizable fetch boundary. Database access and schema ownership are isolated in `lib/db`, configured for Drizzle.

Paths:
- `lib/api-client-react/src/generated/api.ts`
- `lib/api-client-react/src/custom-fetch.ts`
- `lib/db/src/index.ts`
- `lib/db/drizzle.config.ts`

This separation allows frontend callers to depend on generated contract code rather than API-server internals, and keeps persistence details out of route modules.

#### Telegram Integration and Operational Services
The backend includes explicit Telegram and Telegram-bot integrations, likely used for request notifications and/or admin authentication flows defined in the API contract. Logging is also isolated as an infrastructure concern.

Paths:
- `artifacts/api-server/src/lib/telegram.ts`
- `artifacts/api-server/src/lib/telegram-bot.ts`
- `artifacts/api-server/src/lib/logger.ts`

External/runtime boundaries are therefore: browser-to-HTTP API, API-to-database through Drizzle, and API-to-Telegram.

#### Deployment and Build
The repository includes Railway deployment metadata and documentation, a GitHub deployment workflow, and Replit artifact descriptors. The API has its own build script, indicating it is deployed/built independently from frontend artifacts.

Paths:
- `railway.json`
- `RAILWAY_DEPLOY.md`
- `.github/workflows/deploy.yml`
- `artifacts/api-server/build.mjs`

Main entry points: [`artifacts/api-server/src/routes/index.ts`](https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/routes/index.ts) (Route registry), [`artifacts/api-server/src/routes/requests.ts`](https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/routes/requests.ts) (Requests & visit routes), [`artifacts/api-server/src/routes/admin.ts`](https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/routes/admin.ts) (Admin routes), [`lib/api-zod/src/generated/api.ts`](https://github.com/ht1makcv5-create/portfolio/blob/main/lib/api-zod/src/generated/api.ts) (Generated Zod contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Portfolio frontend"]
  node_browser(("Browser visitor<br/>runtime"))
  node_frontend_boot["React bootstrap<br/>Vite entry<br/>[main.tsx]"]
  node_frontend_app["App composition<br/>React app<br/>[App.tsx]"]
  node_portfolio_page["Portfolio page<br/>[portfolio.tsx]"]
end

subgraph group_api["API service"]
  node_api_process["API process<br/>Node entry<br/>[index.ts]"]
  node_api_app["Application composition<br/>server app<br/>[app.ts]"]
  node_route_registry["Route registry<br/>routing<br/>[index.ts]"]
  node_public_routes["Requests &amp; visit routes<br/>public HTTP routes<br/>[requests.ts]"]
  node_admin_routes["Admin routes<br/>admin HTTP routes<br/>[admin.ts]"]
  node_health_routes["Health route<br/>operations route<br/>[health.ts]"]
  node_admin_session["Admin session<br/>authentication<br/>[admin-session.ts]"]
  node_telegram["Telegram integration<br/>external adapter<br/>[telegram.ts]"]
end

subgraph group_shared["Shared contracts &amp; data"]
  node_react_client["Generated React client<br/>API client<br/>[api.ts]"]
  node_custom_fetch["Custom fetch boundary<br/>HTTP adapter<br/>[custom-fetch.ts]"]
  node_openapi_spec["OpenAPI contract<br/>API specification<br/>[openapi.yaml]"]
  node_zod_contract["Generated Zod contract<br/>runtime validation<br/>[api.ts]"]
  node_database_layer[("Drizzle database layer<br/>persistence<br/>[index.ts]")]
end

subgraph group_external["External services"]
  node_telegram_external{{"Telegram platform<br/>external service"}}
end

node_browser -->|"loads SPA"| node_frontend_boot
node_frontend_boot -->|"mounts"| node_frontend_app
node_frontend_app -->|"renders"| node_portfolio_page
node_portfolio_page -->|"submits requests and visits"| node_react_client
node_react_client -->|"uses"| node_custom_fetch
node_custom_fetch -->|"HTTP API calls"| node_api_app
node_api_process -->|"starts"| node_api_app
node_api_app -->|"registers"| node_route_registry
node_route_registry -->|"delegates"| node_public_routes
node_route_registry -->|"delegates"| node_admin_routes
node_route_registry -->|"delegates"| node_health_routes
node_public_routes -->|"persists requests and visits"| node_database_layer
node_admin_routes -->|"reads operational data"| node_database_layer
node_admin_routes -->|"authenticates"| node_admin_session
node_public_routes -->|"notifies"| node_telegram
node_telegram -->|"Telegram API"| node_telegram_external
node_openapi_spec -->|"generates"| node_zod_contract
node_openapi_spec -->|"generates"| node_react_client
node_zod_contract -.->|"validates contract"| node_public_routes
node_zod_contract -.->|"validates contract"| node_admin_routes

click node_frontend_boot "https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/boohx/src/main.tsx"
click node_frontend_app "https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/boohx/src/App.tsx"
click node_portfolio_page "https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/boohx/src/pages/portfolio.tsx"
click node_react_client "https://github.com/ht1makcv5-create/portfolio/blob/main/lib/api-client-react/src/generated/api.ts"
click node_custom_fetch "https://github.com/ht1makcv5-create/portfolio/blob/main/lib/api-client-react/src/custom-fetch.ts"
click node_api_process "https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/index.ts"
click node_api_app "https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/app.ts"
click node_route_registry "https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/routes/index.ts"
click node_public_routes "https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/routes/requests.ts"
click node_admin_routes "https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/routes/admin.ts"
click node_health_routes "https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/routes/health.ts"
click node_admin_session "https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/lib/admin-session.ts"
click node_telegram "https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/lib/telegram.ts"
click node_openapi_spec "https://github.com/ht1makcv5-create/portfolio/blob/main/lib/api-spec/openapi.yaml"
click node_zod_contract "https://github.com/ht1makcv5-create/portfolio/blob/main/lib/api-zod/src/generated/api.ts"
click node_database_layer "https://github.com/ht1makcv5-create/portfolio/blob/main/lib/db/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_frontend_boot,node_frontend_app,node_portfolio_page toneBlue
class node_api_process,node_api_app,node_route_registry,node_public_routes,node_admin_routes,node_health_routes,node_admin_session,node_telegram toneAmber
class node_react_client,node_custom_fetch,node_openapi_spec,node_zod_contract,node_database_layer toneMint
class node_telegram_external toneRose
```

## Components

### Portfolio frontend

- **Browser visitor**: runtime
- [React bootstrap](https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/boohx/src/main.tsx): Vite entry · `artifacts/boohx/src/main.tsx`
- [App composition](https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/boohx/src/App.tsx): React app · `artifacts/boohx/src/App.tsx`
- [Portfolio page](https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/boohx/src/pages/portfolio.tsx): page · Renders portfolio and contact-request UI. · `artifacts/boohx/src/pages/portfolio.tsx`

### API service

- [API process](https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/index.ts): Node entry · `artifacts/api-server/src/index.ts`
- [Application composition](https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/app.ts): server app · `artifacts/api-server/src/app.ts`
- [Route registry](https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/routes/index.ts): routing · `artifacts/api-server/src/routes/index.ts`
- [Requests & visit routes](https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/routes/requests.ts): public HTTP routes · `artifacts/api-server/src/routes/requests.ts`
- [Admin routes](https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/routes/admin.ts): admin HTTP routes · `artifacts/api-server/src/routes/admin.ts`
- [Health route](https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/routes/health.ts): operations route · `artifacts/api-server/src/routes/health.ts`
- [Admin session](https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/lib/admin-session.ts): authentication · `artifacts/api-server/src/lib/admin-session.ts`
- [Telegram integration](https://github.com/ht1makcv5-create/portfolio/blob/main/artifacts/api-server/src/lib/telegram.ts): external adapter · Supports notifications and Telegram-related admin flows. · `artifacts/api-server/src/lib/telegram.ts`

### Shared contracts & data

- [Generated React client](https://github.com/ht1makcv5-create/portfolio/blob/main/lib/api-client-react/src/generated/api.ts): API client · `lib/api-client-react/src/generated/api.ts`
- [Custom fetch boundary](https://github.com/ht1makcv5-create/portfolio/blob/main/lib/api-client-react/src/custom-fetch.ts): HTTP adapter · `lib/api-client-react/src/custom-fetch.ts`
- [OpenAPI contract](https://github.com/ht1makcv5-create/portfolio/blob/main/lib/api-spec/openapi.yaml): API specification · Source boundary for requests, visits, dashboard, and admin sessions. · `lib/api-spec/openapi.yaml`
- [Generated Zod contract](https://github.com/ht1makcv5-create/portfolio/blob/main/lib/api-zod/src/generated/api.ts): runtime validation · `lib/api-zod/src/generated/api.ts`
- [Drizzle database layer](https://github.com/ht1makcv5-create/portfolio/blob/main/lib/db/src/index.ts): persistence · Owns request and visit schema access. · `lib/db/src/index.ts`

### External services

- **Telegram platform**: external service

## Connections

- Browser visitor → React bootstrap: loads SPA
- React bootstrap → App composition: mounts
- App composition → Portfolio page: renders
- Portfolio page → Generated React client: submits requests and visits
- Generated React client → Custom fetch boundary: uses
- Custom fetch boundary → Application composition: HTTP API calls
- API process → Application composition: starts
- Application composition → Route registry: registers
- Route registry → Requests & visit routes: delegates
- Route registry → Admin routes: delegates
- Route registry → Health route: delegates
- Requests & visit routes → Drizzle database layer: persists requests and visits
- Admin routes → Drizzle database layer: reads operational data
- Admin routes → Admin session: authenticates
- Requests & visit routes → Telegram integration: notifies
- Telegram integration → Telegram platform: Telegram API
- OpenAPI contract → Generated Zod contract: generates
- OpenAPI contract → Generated React client: generates
- Generated Zod contract → Requests & visit routes: validates contract
- Generated Zod contract → Admin routes: validates contract