# yaroslavsokoi/int20h-alco-team architecture

> Architecture diagram of the GitHub repository yaroslavsokoi/int20h-alco-team, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yaroslavsokoi/int20h-alco-team
- Repository: https://github.com/yaroslavsokoi/int20h-alco-team

## Overview

AlcoDOLIV is a sales-tax order management system for New York deliveries, with a React admin console and Express API. Its core flow is an authenticated user creating or importing orders; the backend resolves delivery coordinates and tax, then persists results for search, filtering, statistics, and review. User and login administration are separate product branches. The README documents local reverse geocoding, NY boundary checks, composite rates, CSV/JSON import, and Redis caching; these capabilities are included, though some implementation links remain unverified because their sources were not excerpted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/App.tsx) (React application), [`backend/src/app.ts`](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/app.ts) (API server), [`backend/src/services/order.service.ts`](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/services/order.service.ts) (Order workflows), [`backend/src/services/tax.service.ts`](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/services/tax.service.ts) (Composite tax rates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Admin console"]
  node_web["React application<br/>[App.tsx]"]
  node_login["Login page<br/>[LoginPage.tsx]"]
  node_dashboard["Orders dashboard<br/>[DashboardPage.tsx]"]
  node_userspage["User management<br/>[UsersPage.tsx]"]
  node_authstore["Session state<br/>[authStore.ts]"]
  node_orderstore["Order state<br/>[orderStore.ts]"]
  node_orderui["Order table and charts"]
  node_userui["User forms"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["API and access"]
  node_server["API server<br/>[app.ts]"]
  node_authroutes["Auth routes<br/>[auth.routes.ts]"]
  node_orderroutes["Order routes<br/>[order.routes.ts]"]
  node_userroutes["User routes<br/>[user.routes.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_userservice["User operations<br/>[user.service.ts]"]
  node_userrepo["User records<br/>[user.repository.ts]"]
end

subgraph group_orders["Order processing"]
  node_ordercontroller["Order handlers"]
  node_orderservice["Order workflows<br/>[order.service.ts]"]
  node_parsers["CSV and JSON parsing"]
  node_orderrepo["Order queries"]
  node_ordersdb[("Orders database<br/>[db.ts]")]
end

subgraph group_support["Tax and location"]
  node_geocoder["Local geocoder"]
  node_tax["Composite tax rates<br/>[tax.service.ts]"]
  node_taxclient["Tax rate client<br/>[tax.client.ts]"]
  node_redis[("Redis cache<br/>[redis.client.ts]")]
  node_nominatim["Nominatim fallback"]
end

node_admin(("Admin user"))

node_admin -->|"uses"| node_web
node_web -.->|"routes to"| node_login
node_web -.->|"routes to"| node_dashboard
node_web -.->|"routes to"| node_userspage
node_login -.->|"signs in"| node_authstore
node_userspage -.->|"renders"| node_userui
node_dashboard -.->|"renders"| node_orderui
node_orderui -.->|"uses"| node_orderstore
node_authstore -.->|"requests through"| node_api_client
node_orderstore -.->|"requests through"| node_api_client
node_userui -.->|"requests through"| node_api_client
node_api_client -.->|"sends API requests"| node_server
node_server -->|"mounts"| node_authroutes
node_server -->|"mounts"| node_orderroutes
node_server -->|"mounts"| node_userroutes
node_authroutes -->|"dispatches to"| node_auth
node_userroutes -->|"dispatches to"| node_userservice
node_userservice -->|"uses"| node_userrepo
node_auth -->|"looks up users"| node_userrepo
node_orderroutes -->|"dispatches to"| node_ordercontroller
node_ordercontroller -->|"calls"| node_orderservice
node_orderservice -->|"parses imports"| node_parsers
node_orderservice -->|"queries and writes"| node_orderrepo
node_orderrepo -->|"reads and writes"| node_ordersdb
node_orderrepo -->|"parses search"| node_parsers
node_orderservice -->|"calculates tax"| node_tax
node_tax -.->|"resolves jurisdiction"| node_geocoder
node_tax -.->|"gets rates"| node_taxclient
node_taxclient -->|"caches rates"| node_redis
node_geocoder -.->|"caches locations"| node_redis
node_tax -.->|"optional geocoding"| node_nominatim

click node_web "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/App.tsx"
click node_login "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/pages/LoginPage.tsx"
click node_dashboard "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_userspage "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/pages/UsersPage.tsx"
click node_authstore "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/store/authStore.ts"
click node_orderstore "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/store/orderStore.ts"
click node_orderui "https://github.com/yaroslavsokoi/int20h-alco-team/tree/main/frontend/src/features/orders/components"
click node_userui "https://github.com/yaroslavsokoi/int20h-alco-team/tree/main/frontend/src/features/users/components"
click node_api_client "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/api/client.ts"
click node_server "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/app.ts"
click node_authroutes "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/routes/auth.routes.ts"
click node_orderroutes "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/routes/order.routes.ts"
click node_userroutes "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/routes/user.routes.ts"
click node_auth "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/services/auth.service.ts"
click node_userservice "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/services/user.service.ts"
click node_userrepo "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/repositories/user.repository.ts"
click node_ordercontroller "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/controllers/order.controller.ts"
click node_orderservice "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/services/order.service.ts"
click node_parsers "https://github.com/yaroslavsokoi/int20h-alco-team/tree/main/backend/src/utils"
click node_orderrepo "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/repositories/order.repository.ts"
click node_ordersdb "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/repositories/db.ts"
click node_geocoder "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/clients/local-geocoder.client.ts"
click node_tax "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/services/tax.service.ts"
click node_taxclient "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/clients/tax.client.ts"
click node_redis "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/clients/redis.client.ts"
click node_nominatim "https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/clients/nominatim.client.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_web,node_login,node_dashboard,node_userspage,node_authstore,node_orderstore,node_orderui,node_userui,node_api_client,node_admin toneBlue
class node_server,node_authroutes,node_orderroutes,node_userroutes,node_auth,node_userservice,node_userrepo toneAmber
class node_ordercontroller,node_orderservice,node_parsers,node_orderrepo,node_ordersdb toneMint
class node_geocoder,node_tax,node_taxclient,node_redis,node_nominatim toneRose
```

## Components

### Admin console

- [React application](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Login page](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/pages/LoginPage.tsx): `frontend/src/pages/LoginPage.tsx`
- [Orders dashboard](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/pages/DashboardPage.tsx): `frontend/src/pages/DashboardPage.tsx`
- [User management](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/pages/UsersPage.tsx): `frontend/src/pages/UsersPage.tsx`
- [Session state](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/store/authStore.ts): `frontend/src/store/authStore.ts`
- [Order state](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/store/orderStore.ts): `frontend/src/store/orderStore.ts`
- [Order table and charts](https://github.com/yaroslavsokoi/int20h-alco-team/tree/main/frontend/src/features/orders/components): `frontend/src/features/orders/components`
- [User forms](https://github.com/yaroslavsokoi/int20h-alco-team/tree/main/frontend/src/features/users/components): `frontend/src/features/users/components`
- [API client](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API and access

- [API server](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Auth routes](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/routes/auth.routes.ts): `backend/src/routes/auth.routes.ts`
- [Order routes](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/routes/order.routes.ts): `backend/src/routes/order.routes.ts`
- [User routes](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/routes/user.routes.ts): `backend/src/routes/user.routes.ts`
- [Authentication](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/services/auth.service.ts): `backend/src/services/auth.service.ts`
- [User operations](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/services/user.service.ts): `backend/src/services/user.service.ts`
- [User records](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/repositories/user.repository.ts): `backend/src/repositories/user.repository.ts`

### Order processing

- [Order handlers](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/controllers/order.controller.ts): `backend/src/controllers/order.controller.ts`
- [Order workflows](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/services/order.service.ts): `backend/src/services/order.service.ts`
- [CSV and JSON parsing](https://github.com/yaroslavsokoi/int20h-alco-team/tree/main/backend/src/utils): `backend/src/utils`
- [Order queries](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/repositories/order.repository.ts): `backend/src/repositories/order.repository.ts`
- [Orders database](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/repositories/db.ts): `backend/src/repositories/db.ts`

### Tax and location

- [Local geocoder](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/clients/local-geocoder.client.ts): `backend/src/clients/local-geocoder.client.ts`
- [Composite tax rates](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/services/tax.service.ts): `backend/src/services/tax.service.ts`
- [Tax rate client](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/clients/tax.client.ts): `backend/src/clients/tax.client.ts`
- [Redis cache](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/clients/redis.client.ts): `backend/src/clients/redis.client.ts`
- [Nominatim fallback](https://github.com/yaroslavsokoi/int20h-alco-team/blob/main/backend/src/clients/nominatim.client.ts): `backend/src/clients/nominatim.client.ts`

### Other components

- **Admin user**

## Connections

- Admin user → React application: uses
- React application → Login page: routes to
- React application → Orders dashboard: routes to
- React application → User management: routes to
- Login page → Session state: signs in
- User management → User forms: renders
- Orders dashboard → Order table and charts: renders
- Order table and charts → Order state: uses
- Session state → API client: requests through
- Order state → API client: requests through
- User forms → API client: requests through
- API client → API server: sends API requests
- API server → Auth routes: mounts (evidence: `backend/src/app.ts`)
- API server → Order routes: mounts (evidence: `backend/src/app.ts`)
- API server → User routes: mounts (evidence: `backend/src/app.ts`)
- Auth routes → Authentication: dispatches to (evidence: `backend/src/routes/auth.routes.ts`)
- User routes → User operations: dispatches to (evidence: `backend/src/routes/user.routes.ts`)
- User operations → User records: uses (evidence: `backend/src/services/user.service.ts`)
- Authentication → User records: looks up users (evidence: `backend/src/services/auth.service.ts`)
- Order routes → Order handlers: dispatches to (evidence: `backend/src/routes/order.routes.ts`)
- Order handlers → Order workflows: calls (evidence: `backend/src/controllers/order.controller.ts`)
- Order workflows → CSV and JSON parsing: parses imports (evidence: `backend/src/services/order.service.ts`)
- Order workflows → Order queries: queries and writes (evidence: `backend/src/services/order.service.ts`)
- Order queries → Orders database: reads and writes (evidence: `backend/src/repositories/order.repository.ts`)
- Order queries → CSV and JSON parsing: parses search (evidence: `backend/src/repositories/order.repository.ts`)
- Order workflows → Composite tax rates: calculates tax (evidence: `backend/src/services/order.service.ts`)
- Composite tax rates → Local geocoder: resolves jurisdiction
- Composite tax rates → Tax rate client: gets rates
- Tax rate client → Redis cache: caches rates (evidence: `backend/src/clients/tax.client.ts`)
- Local geocoder → Redis cache: caches locations
- Composite tax rates → Nominatim fallback: optional geocoding
