# antonio-valdovinos/barbershop-web-system architecture

> Architecture diagram of the GitHub repository antonio-valdovinos/barbershop-web-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/antonio-valdovinos/barbershop-web-system
- Repository: https://github.com/antonio-valdovinos/barbershop-web-system

## Overview

This repository is a two-tier fullstack barbershop management system with a clear split between a React frontend and a Node/Express backend connected to MongoDB Atlas.

At a high level, the architecture is:

- Frontend: user interface and client-side navigation
- Backend: HTTP API and business logic
- Database: MongoDB for persistent operational data
- Seed/bootstrap layer: initial data setup for the barbershop domain

#### 1) Frontend subsystem

The frontend lives in `frontend/` and is built with:

- React
- Vite as the build/dev server
- Tailwind CSS for styling

##### Main frontend entry points
- `src/main.jsx` is the application bootstrap.
- `src/App.jsx` is the top-level composition point, likely where routes and layout are wired.
- `src/index.css` provides global styling.

##### Frontend structure
The UI is organized by page-level components under `src/pages/`. This strongly suggests a route-driven architecture where each page corresponds to a user flow or role.

There are three major UI groupings:

###### Public / customer-facing pages
- `HomePage.jsx`
- `LoginPage.jsx`
- `RegisterPage.jsx`
- `AgendarCitaPage.jsx`
- `MisCitasPage.jsx`

These pages cover discovery, authentication, appointment booking, and viewing a user’s own appointments.

###### Administrative pages
- `AdminDashboardPage.jsx`
- `AdminCitasPage.jsx`
- `AdminClientesPage.jsx`
- `AdminAgregarClientePage.jsx`
- `AdminServiciosPage.jsx`
- `AdminAgregarServicioPage.jsx`
- `AdminHorariosPage.jsx`
- `AdminConfigPage.jsx`

These pages support operational management: appointments, customers, services, schedules, and configuration.

##### Frontend role in the architecture
The frontend does not appear to contain server logic or persistence. Its responsibility is:

- rendering the UI
- collecting user input
- navigating between customer/admin views
- calling the backend API over HTTP for data access and updates

This makes the frontend a presentation and interaction layer, not a source of truth.

---

#### 2) Backend subsystem

The backend lives in `backend/` and is structured as a classic Express API with a resource-oriented organization.

##### Backend entry and bootstrap
- `src/server.js` is the application entry point.
- `src/config/db.js` centralizes the MongoDB connection setup.

This suggests the server starts by:
1. loading environment configuration
2. connecting to MongoDB
3. registering routes/controllers
4. starting the HTTP listener

##### Backend layering
The backend is split into:

###### Routes
Located in `src/routes/`:
- `citasRoutes.js`
- `clientesRoutes.js`
- `horariosRoutes.js`
- `serviciosRoutes.js`
- `usuariosRoutes.js`

These define the API surface and map URL paths and HTTP methods to controller actions.

###### Controllers
Located in `src/controllers/`:
- `citasController.js`
- `clientesController.js`
- `horariosController.js`
- `serviciosController.js`
- `usuariosController.js`

These contain the request-handling logic and business rules. They sit between routes and data models.

###### Models
Located in `src/models/`:
- `Cita.js`
- `Cliente.js`
- `Horario.js`

These represent persisted domain entities in MongoDB. Even though only three model files are visible in the tree, the controller/route structure indicates the system is organized around the same set of business resources plus services and users.

##### Backend responsibilities
The backend is the authoritative layer for:

- appointment creation and management
- client record management
- service catalog management
- schedule/availability management
- user-related operations
- data validation and rule enforcement
- persistence to MongoDB

This is the main boundary where business logic lives. The frontend should not directly manipulate data storage.

---

#### 3) Persistence layer

The database is MongoDB, with the README explicitly calling out MongoDB Atlas.

That means the system uses a cloud-hosted NoSQL datastore for:

- appointments
- customers
- schedules
- services
- users or authentication-related records

The important architectural point is that persistence is externalized from the application server, so the backend communicates with a managed database service rather than embedding data locally.

`src/config/db.js` is the central integration point for this external dependency.

---

#### 4) Seed / initialization layer

The backend includes `src/seed/seedBarberia.js`.

This is a bootstrap/fixture script used to pre-populate the application with initial barbershop data. Architecturally, that means the system supports:

- repeatable setup of baseline domain records
- development or deployment initialization
- quick restoration of known starting state

This is separate from normal runtime request handling and should be treated as an operational utility, not part of the request/response path.

---

#### 5) Main data flows

##### Customer appointment flow
1. User opens the frontend.
2. User navigates to booking or account pages.
3. Frontend submits appointment or profile-related requests to the backend API.
4. Backend validates the request, applies business rules, and writes to MongoDB.
5. Backend returns the result.
6. Frontend updates the UI to reflect confirmation, errors, or current state.

##### Admin management flow
1. Admin logs in through the frontend.
2. Admin accesses dashboard or management pages.
3. Frontend fetches lists and detail views from the backend.
4. Admin actions such as add/edit/view appointments, clients, services, or schedules are sent to the backend.
5. Backend controllers update the database.
6. Frontend refreshes data for operational oversight.

##### Initialization flow
1. Seed script runs manually or during setup.
2. It inserts initial barbershop data into MongoDB.
3. The application then consumes that data through the normal API path.

---

#### 6) Architectural boundaries

The important boundaries in this repository are:

##### Frontend vs backend
- Frontend owns user interaction and view composition.
- Backend owns business logic and persistence access.

##### API boundary
- The frontend talks to the backend only through HTTP routes.
- Route files define the contract surface for each business area.

##### Controller vs model boundary
- Controllers contain orchestration and business decisions.
- Models represent the stored domain objects.

##### Runtime vs initialization boundary
- `server.js` runs the application service.
- `seedBarberia.js` is a separate setup utility.

---

#### 7) What this suggests for a diagram

A good architecture diagram for this repo would show:

- A browser/client on the left
- React/Vite/Tailwind frontend in the middle-left as the UI layer
- Express backend in the middle-right as the API/application layer
- Route/controller/model separation inside the backend
- MongoDB Atlas on the right as the data store
- A separate seed/init component feeding MongoDB during setup

The key domain areas to label are:
- appointments
- clients
- services
- schedules
- users/authentication
- admin management

Overall, this is a straightforward layered fullstack system with a resource-based API backend and a page-oriented React frontend, designed around barbershop operations rather than a generic CRUD app.

Main entry points: [`backend/src/routes/citasRoutes.js`](https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/routes/citasRoutes.js) (Routes), [`frontend/src/App.jsx`](https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/frontend/src/App.jsx) (App), [`backend/src/controllers/citasController.js`](https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/controllers/citasController.js) (Controllers), [`backend/src/config/db.js`](https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/config/db.js) (DB config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_main["Main<br/>React bootstrap<br/>[main.jsx]"]
  node_fe_app["App<br/>UI shell<br/>[App.jsx]"]
  node_fe_public["Customer pages<br/>[HomePage.jsx]"]
  node_fe_admin["Admin pages"]
end

subgraph group_backend["Backend"]
  node_be_server["Server<br/>Express entry<br/>[server.js]"]
  node_be_db["DB config<br/>Mongo connector<br/>[db.js]"]
  node_be_routes["Routes<br/>[citasRoutes.js]"]
  node_be_controllers["Controllers<br/>Business logic<br/>[citasController.js]"]
  node_be_models[("Models<br/>[Cita.js]")]
  node_be_seed["Seeder<br/>Bootstrap script<br/>[seedBarberia.js]"]
end

subgraph group_data["Data"]
  node_db_mongo[("MongoDB Atlas<br/>NoSQL store")]
end

node_fe_main -->|"boots"| node_fe_app
node_fe_app -->|"renders"| node_fe_public
node_fe_app -->|"renders"| node_fe_admin
node_fe_public -->|"calls API"| node_be_routes
node_fe_admin -->|"calls API"| node_be_routes
node_be_server -->|"connects"| node_be_db
node_be_server -->|"mounts"| node_be_routes
node_be_routes -->|"delegates"| node_be_controllers
node_be_controllers -->|"uses"| node_be_models
node_be_controllers -->|"persists via"| node_be_db
node_be_models -->|"stores in"| node_db_mongo
node_be_db -->|"connects to"| node_db_mongo
node_be_seed -->|"seeds"| node_db_mongo

click node_fe_main "https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/frontend/src/main.jsx"
click node_fe_app "https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/frontend/src/App.jsx"
click node_fe_public "https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/frontend/src/pages/HomePage.jsx"
click node_fe_admin "https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/frontend/src/pages/AdminDashboardPage.jsx"
click node_be_server "https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/server.js"
click node_be_db "https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/config/db.js"
click node_be_routes "https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/routes/citasRoutes.js"
click node_be_controllers "https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/controllers/citasController.js"
click node_be_models "https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/models/Cita.js"
click node_be_seed "https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/seed/seedBarberia.js"

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_fe_main,node_fe_app,node_fe_public,node_fe_admin toneBlue
class node_be_server,node_be_db,node_be_routes,node_be_controllers,node_be_models,node_be_seed toneAmber
class node_db_mongo toneMint
```

## Components

### Frontend

React/Vite UI layer and page-driven user flows

- [Main](https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/frontend/src/main.jsx): React bootstrap · Application entry and client startup · `frontend/src/main.jsx`
- [App](https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/frontend/src/App.jsx): UI shell · Top-level composition and routing · `frontend/src/App.jsx`
- [Customer pages](https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/frontend/src/pages/HomePage.jsx): Pages · Home, auth, booking, and self-service views · `frontend/src/pages/HomePage.jsx`
- [Admin pages](https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/frontend/src/pages/AdminDashboardPage.jsx): Pages · Dashboard and operational management views · `frontend/src/pages/AdminDashboardPage.jsx`

### Backend

Express API, business logic, and persistence integration

- [Server](https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/server.js): Express entry · Backend startup and HTTP listener · `backend/src/server.js`
- [DB config](https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/config/db.js): Mongo connector · Central MongoDB connection setup · `backend/src/config/db.js`
- [Routes](https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/routes/citasRoutes.js): API routes · Resource endpoints for appointments, clients, schedules, services, and users · `backend/src/routes/citasRoutes.js`
- [Controllers](https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/controllers/citasController.js): Business logic · Request handling and domain orchestration · `backend/src/controllers/citasController.js`
- [Models](https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/models/Cita.js): Domain models · Mongo-backed entities for core barbershop records · `backend/src/models/Cita.js`
- [Seeder](https://github.com/antonio-valdovinos/barbershop-web-system/blob/main/backend/src/seed/seedBarberia.js): Bootstrap script · Initial barbershop data population · `backend/src/seed/seedBarberia.js`

### Data

MongoDB Atlas persistence

- **MongoDB Atlas**: NoSQL store · Persistent operational data store

## Connections

- Main → App: boots · Client starts the app shell
- App → Customer pages: renders · Routes customer-facing flows
- App → Admin pages: renders · Routes admin management flows
- Customer pages → Routes: calls API · Submits booking and account requests
- Admin pages → Routes: calls API · Fetches and mutates operational data
- Server → DB config: connects · Initializes database connectivity
- Server → Routes: mounts · Registers API endpoints
- Routes → Controllers: delegates · Maps HTTP requests to handlers
- Controllers → Models: uses · Reads and writes domain entities
- Controllers → DB config: persists via · Coordinates access through Mongo connection
- Models → MongoDB Atlas: stores in · Persists operational records
- DB config → MongoDB Atlas: connects to · Links backend runtime to Atlas
- Seeder → MongoDB Atlas: seeds · Populates baseline data
