# mayank11104/team_code200 architecture

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

- Interactive diagram: https://gitdiagram.com/mayank11104/team_code200
- Repository: https://github.com/mayank11104/team_code200

## Overview

1. **Overall shape**
GearGuard is a two-tier maintenance management system: a Python backend exposes application data and workflow rules, while a React/TypeScript frontend renders operational views such as dashboard, list, kanban, calendar, and detail pages. The database is designed as the system of record and is shared directly via SQL schema/seed files.

2. **Backend boundary**
The backend is organized as a classic layered API service:
- `backend/main.py` is the entrypoint.
- `backend/api/` contains route modules grouped by domain: `auth`, `equipment`, `maintenance`, `reports`, and `teams`.
- `backend/services/` holds business logic such as user management and audit tracking.
- `backend/models/` contains data models for users, tokens, and login history.
- `backend/core/` centralizes configuration, database access, and security utilities.

This separation suggests request handling is kept thin, with workflow rules and persistence behavior pushed into services/core modules.

3. **Domain modules and responsibilities**
The main domain boundaries are explicit in the backend API:
- **Auth**: login/session/token handling and identity.
- **Equipment**: asset registry and equipment lifecycle, including scrap behavior.
- **Maintenance**: corrective/preventive request creation and status transitions.
- **Teams**: maintenance team and technician management.
- **Reports**: aggregated operational views and metrics.

These correspond closely to the UI screens, so the architecture is domain-aligned rather than technical-layer aligned.

4. **Business workflow**
The central workflow is maintenance request processing:
equipment is selected, a maintenance team is inherited from that equipment, requests start in `New`, then move through `In Progress`, and finally to `Repaired` or `Scrap`. The readme also calls out technician assignment and preventive maintenance scheduling via `scheduled_date`. This means the backend is not just CRUD; it enforces a state machine around requests.

5. **Security and access control**
Role-based access control is a major architectural concern. The readme defines Admin/Manager, Technician, and Employee roles, and the backend includes `security.py`, token models, and login history tracking. That implies authenticated requests are authorized by role and identity, with token/session handling likely centralized in the core security layer.

6. **Audit and traceability**
The system emphasizes auditability:
- `login_history` and `token` models support authentication traceability.
- The readme mentions request status change history.
- Soft deletes are used across entities via `deleted_at`.
This means the data model is designed to preserve operational history rather than hard-delete records, which is important for ERP-style reporting and compliance.

7. **Database as a first-class component**
The repository includes explicit SQL assets under `backend/database/`:
- `schema.sql` defines the normalized schema.
- `seed.sql` provides demo/reference data.
- `setup_database.sql` suggests repeatable local initialization.
The readme states the schema is in 3NF with junction tables for many-to-many relationships, so the database layer is intentionally authoritative and shared across the team.

8. **Frontend structure**
The frontend is a Vite-based React application using TypeScript and a component-heavy design system. It is organized into:
- `pages/` for route-level screens like Dashboard, Equipment, Teams, Calendar, Reports, Login/SignUp modals, and detail pages.
- `components/` for reusable UI and domain widgets.
- `components/ui/` for a large shadcn-style primitive library.
- `components/layout/` for shell structure such as top bar and app layout.

This indicates the UI is built from reusable primitives plus domain-specific composites, not from one monolithic page layer.

9. **Frontend data flow**
The frontend reads backend data through `src/api/client.ts`, `src/api/endpoints.ts`, and feature-specific hooks such as `useEquipment`, `useMaintenance`, `useReports`, and `useTeams`. That structure suggests a clean split between transport/client logic and view logic. Pages consume hooks, hooks call endpoints, and components render data states.

10. **UI feature mapping**
The main screens map directly to backend domains:
- Dashboard and Reports show aggregated operational data.
- Equipment pages manage assets and equipment details.
- Maintenance pages manage requests, including kanban and lists.
- Teams pages manage maintenance groups and technicians.
- Calendar focuses on preventive maintenance scheduling.
This makes the frontend a presentation layer over the backend workflow model, not an independent domain engine.

11. **Mock vs live data**
There is a `src/data/mockData.ts` file, which likely supports local development or placeholder rendering, but the README says frontend data is dynamically loaded from the database. Architecturally, mock data appears supplemental rather than primary.

12. **Operational setup**
The repo is structured for collaborative development:
- PostgreSQL is the external infrastructure dependency.
- Schema and seed files are version-controlled.
- Frontend and backend are kept aligned with the same field names and workflow rules.
- `fix_table_names.py` hints at migration/compatibility maintenance around schema naming.
This reinforces that the project is designed around stable database contracts and a clear separation between UI, API, and persistence.

Main entry points: [`backend/api`](https://github.com/mayank11104/team_code200/tree/main/backend/api) (API routes), [`frontend/src/pages`](https://github.com/mayank11104/team_code200/tree/main/frontend/src/pages) (Pages), [`backend/database/schema.sql`](https://github.com/mayank11104/team_code200/blob/main/backend/database/schema.sql) (Schema), [`backend/core`](https://github.com/mayank11104/team_code200/tree/main/backend/core) (Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["main.py<br/>api entrypoint<br/>[main.py]"]
  node_backend_api["API routes<br/>domain routers"]
  node_backend_auth["Auth<br/>[auth.py]"]
  node_backend_equipment["Equipment<br/>[equipment.py]"]
  node_backend_maintenance["Maintenance<br/>workflow routes<br/>[maintenance.py]"]
  node_backend_reports["Reports<br/>report routes<br/>[reports.py]"]
  node_backend_teams["Teams<br/>team routes<br/>[teams.py]"]
  node_backend_core["Core<br/>shared services"]
  node_backend_models["Models"]
  node_backend_services["Services<br/>business logic"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>react app<br/>[App.tsx]"]
  node_frontend_pages["Pages<br/>route views"]
  node_frontend_components["Components<br/>ui composites"]
  node_frontend_ui["UI kit<br/>primitive components"]
  node_frontend_api["API client<br/>data access"]
  node_frontend_mock["Mock data<br/>sample data<br/>[mockData.ts]"]
end

subgraph group_database["Database"]
  node_backend_db_schema["Schema<br/>[schema.sql]"]
  node_backend_db_seed["Seed data<br/>sql seed<br/>[seed.sql]"]
  node_backend_db_setup["Setup SQL<br/>init script<br/>[setup_database.sql]"]
end

node_backend_main -->|"serves"| node_backend_api
node_backend_api -->|"contains"| node_backend_auth
node_backend_api -->|"contains"| node_backend_equipment
node_backend_api -->|"contains"| node_backend_maintenance
node_backend_api -->|"contains"| node_backend_reports
node_backend_api -->|"contains"| node_backend_teams
node_backend_api -->|"uses"| node_backend_core
node_backend_api -->|"delegates"| node_backend_services
node_backend_services -->|"persists"| node_backend_models
node_backend_core -->|"backs"| node_backend_db_schema
node_backend_core -->|"initializes"| node_backend_db_setup
node_backend_models -->|"maps to"| node_backend_db_schema
node_frontend_app -->|"composes"| node_frontend_pages
node_frontend_pages -->|"uses"| node_frontend_components
node_frontend_components -->|"builds on"| node_frontend_ui
node_frontend_pages -->|"loads data"| node_frontend_api
node_frontend_api -->|"calls"| node_backend_api
node_frontend_pages -.->|"falls back to"| node_frontend_mock
node_backend_reports -->|"queries"| node_backend_db_schema
node_backend_maintenance -->|"updates"| node_backend_db_schema

click node_backend_main "https://github.com/mayank11104/team_code200/blob/main/backend/main.py"
click node_backend_api "https://github.com/mayank11104/team_code200/tree/main/backend/api"
click node_backend_auth "https://github.com/mayank11104/team_code200/blob/main/backend/api/auth.py"
click node_backend_equipment "https://github.com/mayank11104/team_code200/blob/main/backend/api/equipment.py"
click node_backend_maintenance "https://github.com/mayank11104/team_code200/blob/main/backend/api/maintenance.py"
click node_backend_reports "https://github.com/mayank11104/team_code200/blob/main/backend/api/reports.py"
click node_backend_teams "https://github.com/mayank11104/team_code200/blob/main/backend/api/teams.py"
click node_backend_core "https://github.com/mayank11104/team_code200/tree/main/backend/core"
click node_backend_models "https://github.com/mayank11104/team_code200/tree/main/backend/models"
click node_backend_services "https://github.com/mayank11104/team_code200/tree/main/backend/services"
click node_backend_db_schema "https://github.com/mayank11104/team_code200/blob/main/backend/database/schema.sql"
click node_backend_db_seed "https://github.com/mayank11104/team_code200/blob/main/backend/database/seed.sql"
click node_backend_db_setup "https://github.com/mayank11104/team_code200/blob/main/backend/database/setup_database.sql"
click node_frontend_app "https://github.com/mayank11104/team_code200/blob/main/frontend/src/App.tsx"
click node_frontend_pages "https://github.com/mayank11104/team_code200/tree/main/frontend/src/pages"
click node_frontend_components "https://github.com/mayank11104/team_code200/tree/main/frontend/src/components"
click node_frontend_ui "https://github.com/mayank11104/team_code200/tree/main/frontend/src/components/ui"
click node_frontend_api "https://github.com/mayank11104/team_code200/tree/main/frontend/src/api"
click node_frontend_mock "https://github.com/mayank11104/team_code200/blob/main/frontend/src/data/mockData.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_backend_main,node_backend_api,node_backend_auth,node_backend_equipment,node_backend_maintenance,node_backend_reports,node_backend_teams,node_backend_core,node_backend_models,node_backend_services toneBlue
class node_frontend_app,node_frontend_pages,node_frontend_components,node_frontend_ui,node_frontend_api,node_frontend_mock toneAmber
class node_backend_db_schema,node_backend_db_seed,node_backend_db_setup toneMint
```

## Components

### Backend

Python API service, business logic, and shared persistence/security core.

- [main.py](https://github.com/mayank11104/team_code200/blob/main/backend/main.py): api entrypoint · Starts the backend application and wires the API service. · `backend/main.py`
- [API routes](https://github.com/mayank11104/team_code200/tree/main/backend/api): domain routers · Thin HTTP route modules organized by business domain. · `backend/api`
- [Auth](https://github.com/mayank11104/team_code200/blob/main/backend/api/auth.py): auth routes · Login, session, and token-related request handling. · `backend/api/auth.py`
- [Equipment](https://github.com/mayank11104/team_code200/blob/main/backend/api/equipment.py): equipment routes · Asset registry and equipment lifecycle endpoints. · `backend/api/equipment.py`
- [Maintenance](https://github.com/mayank11104/team_code200/blob/main/backend/api/maintenance.py): workflow routes · Maintenance request creation, assignment, and status transitions. · `backend/api/maintenance.py`
- [Reports](https://github.com/mayank11104/team_code200/blob/main/backend/api/reports.py): report routes · Aggregated operational views and metrics endpoints. · `backend/api/reports.py`
- [Teams](https://github.com/mayank11104/team_code200/blob/main/backend/api/teams.py): team routes · Maintenance team and technician management endpoints. · `backend/api/teams.py`
- [Core](https://github.com/mayank11104/team_code200/tree/main/backend/core): shared services · Central configuration, database access, and security utilities. · `backend/core`
- [Models](https://github.com/mayank11104/team_code200/tree/main/backend/models): data models · User, token, and login history persistence models. · `backend/models`
- [Services](https://github.com/mayank11104/team_code200/tree/main/backend/services): business logic · Application logic for user management and audit tracking. · `backend/services`

### Frontend

React/TypeScript presentation layer with reusable UI and feature hooks.

- [App shell](https://github.com/mayank11104/team_code200/blob/main/frontend/src/App.tsx): react app · Top-level application composition and routing shell. · `frontend/src/App.tsx`
- [Pages](https://github.com/mayank11104/team_code200/tree/main/frontend/src/pages): route views · Route-level screens for dashboard, lists, details, and modals. · `frontend/src/pages`
- [Components](https://github.com/mayank11104/team_code200/tree/main/frontend/src/components): ui composites · Reusable domain widgets and layout components. · `frontend/src/components`
- [UI kit](https://github.com/mayank11104/team_code200/tree/main/frontend/src/components/ui): primitive components · Reusable shadcn-style UI primitives. · `frontend/src/components/ui`
- [API client](https://github.com/mayank11104/team_code200/tree/main/frontend/src/api): data access · HTTP client, endpoint definitions, and feature hooks. · `frontend/src/api`
- [Mock data](https://github.com/mayank11104/team_code200/blob/main/frontend/src/data/mockData.ts): sample data · Supplemental local-development placeholder data. · `frontend/src/data/mockData.ts`

### Database

Versioned SQL schema, seeds, and initialization assets.

- [Schema](https://github.com/mayank11104/team_code200/blob/main/backend/database/schema.sql): sql schema · Normalized PostgreSQL schema definition. · `backend/database/schema.sql`
- [Seed data](https://github.com/mayank11104/team_code200/blob/main/backend/database/seed.sql): sql seed · Demo and reference data for local setup. · `backend/database/seed.sql`
- [Setup SQL](https://github.com/mayank11104/team_code200/blob/main/backend/database/setup_database.sql): init script · Repeatable database initialization script. · `backend/database/setup_database.sql`

## Connections

- main.py → API routes: serves · Entrypoint exposes the domain routers.
- API routes → Auth: contains · Auth routes are one domain boundary.
- API routes → Equipment: contains · Equipment routes are one domain boundary.
- API routes → Maintenance: contains · Maintenance routes are one domain boundary.
- API routes → Reports: contains · Reports routes are one domain boundary.
- API routes → Teams: contains · Teams routes are one domain boundary.
- API routes → Core: uses · Routes rely on shared config, database, and security helpers.
- API routes → Services: delegates · Request handlers delegate business logic to services.
- Services → Models: persists · Services coordinate model-backed data.
- Core → Schema: backs · Core database layer aligns with the versioned schema.
- Core → Setup SQL: initializes · Core database setup is supported by initialization SQL.
- Models → Schema: maps to · Models reflect the normalized database schema.
- App shell → Pages: composes · App shell renders the route-level screens.
- Pages → Components: uses · Pages assemble reusable domain widgets and layout pieces.
- Components → UI kit: builds on · Composite components are built from UI primitives.
- Pages → API client: loads data · Pages consume feature hooks and endpoint clients.
- API client → API routes: calls · Frontend data access targets backend domain APIs.
- Pages → Mock data: falls back to · Mock data supports placeholder or local rendering.
- Reports → Schema: queries · Reporting endpoints aggregate data from the system of record.
- Maintenance → Schema: updates · Maintenance workflow reads and writes shared persistence state.