# milad-mma/faipco-portal architecture

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

- Interactive diagram: https://gitdiagram.com/milad-mma/faipco-portal
- Repository: https://github.com/milad-mma/faipco-portal

## Overview

FAIPCO Portal is an organization-wide HR and employee self-service portal. Users enter through the React PWA, authenticate, and use routed portal features backed by a FastAPI API and PostgreSQL; employee records can also be synchronized from heterogeneous site databases. The README documents additional workflows including notices/payroll, GPS attendance, leave and loan approvals, evaluations, backups, and push notifications. Some feature implementations were not sampled, so their relationships are shown only where the README documents them; source-level links are limited to indexed or excerpted evidence.

Main entry points: [`frontend/src/main.jsx`](https://github.com/milad-mma/faipco-portal/blob/main/frontend/src/main.jsx) (React portal), [`backend/app/services/auth_service.py`](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/services/auth_service.py) (Authentication service), [`backend/app/sync_engine/sync_service.py`](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/sync_engine/sync_service.py) (Employee sync), [`frontend/src/App.jsx`](https://github.com/milad-mma/faipco-portal/blob/main/frontend/src/App.jsx) (Portal routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Portal client"]
  node_frontend["React portal<br/>[main.jsx]"]
  node_routes["Portal routes<br/>[App.jsx]"]
  node_auth_state["Session context<br/>[AuthContext.jsx]"]
  node_http_client["API client<br/>[client.js]"]
end

subgraph group_api["API and identity"]
  node_api_router["API router<br/>[router.py]"]
  node_auth_endpoint["Authentication API<br/>[auth.py]"]
  node_auth_logic["Authentication service<br/>[auth_service.py]"]
  node_sessions["Device sessions<br/>[session_service.py]"]
end

subgraph group_people["People and operations"]
  node_employee_data[("Employee records<br/>[employee.py]")]
  node_hr_services["HR workflows"]
  node_notices["Notices and payroll<br/>[notices.py]"]
  node_gps["GPS attendance<br/>[attendance.py]"]
  node_evaluations["Performance evaluation"]
  node_office_automation["Office automation<br/>[automation.py]"]
end

subgraph group_integrations["Site integrations"]
  node_sync["Employee sync<br/>[sync_service.py]"]
  node_site_db[("Site databases")]
end

subgraph group_platform["Portal platform"]
  node_portal_db[("Portal database<br/>[session.py]")]
  node_backup["Backup and recovery<br/>[backup.py]"]
  node_push["Web Push<br/>[push.py]"]
end

node_employee(("Employees"))

node_employee -->|"uses"| node_frontend
node_frontend -->|"renders"| node_routes
node_routes -->|"guards routes"| node_auth_state
node_auth_state -->|"requests identity"| node_http_client
node_frontend -.->|"calls API"| node_api_router
node_api_router -->|"registers"| node_auth_endpoint
node_auth_endpoint -->|"delegates"| node_auth_logic
node_auth_logic -->|"manages sessions"| node_sessions
node_auth_logic -.->|"queries"| node_portal_db
node_sync -->|"reads employees"| node_site_db
node_sync -->|"synchronizes"| node_employee_data
node_employee_data -->|"stored in"| node_portal_db
node_employee -->|"uses"| node_hr_services
node_employee -->|"reads notices"| node_notices
node_employee -->|"records attendance"| node_gps
node_employee -->|"completes evaluations"| node_evaluations
node_employee -->|"submits requests"| node_office_automation
node_employee -->|"uses administration"| node_backup
node_employee -->|"receives alerts"| node_push

click node_frontend "https://github.com/milad-mma/faipco-portal/blob/main/frontend/src/main.jsx"
click node_routes "https://github.com/milad-mma/faipco-portal/blob/main/frontend/src/App.jsx"
click node_auth_state "https://github.com/milad-mma/faipco-portal/blob/main/frontend/src/context/AuthContext.jsx"
click node_http_client "https://github.com/milad-mma/faipco-portal/blob/main/frontend/src/api/client.js"
click node_api_router "https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/router.py"
click node_auth_endpoint "https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/endpoints/auth.py"
click node_auth_logic "https://github.com/milad-mma/faipco-portal/blob/main/backend/app/services/auth_service.py"
click node_sessions "https://github.com/milad-mma/faipco-portal/blob/main/backend/app/services/session_service.py"
click node_portal_db "https://github.com/milad-mma/faipco-portal/blob/main/backend/app/db/session.py"
click node_employee_data "https://github.com/milad-mma/faipco-portal/blob/main/backend/app/models/employee.py"
click node_sync "https://github.com/milad-mma/faipco-portal/blob/main/backend/app/sync_engine/sync_service.py"
click node_hr_services "https://github.com/milad-mma/faipco-portal/tree/main/backend/app/services"
click node_notices "https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/endpoints/notices.py"
click node_gps "https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/endpoints/attendance.py"
click node_evaluations "https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/endpoints/evaluation_process.py"
click node_office_automation "https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/endpoints/automation.py"
click node_backup "https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/endpoints/backup.py"
click node_push "https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/endpoints/push.py"

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_frontend,node_routes,node_auth_state,node_http_client toneBlue
class node_api_router,node_auth_endpoint,node_auth_logic,node_sessions toneAmber
class node_employee_data,node_hr_services,node_notices,node_gps,node_evaluations,node_office_automation toneMint
class node_sync,node_site_db toneRose
class node_portal_db,node_backup,node_push,node_employee toneIndigo
```

## Components

### Portal client

- [React portal](https://github.com/milad-mma/faipco-portal/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Portal routes](https://github.com/milad-mma/faipco-portal/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Session context](https://github.com/milad-mma/faipco-portal/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [API client](https://github.com/milad-mma/faipco-portal/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### API and identity

- [API router](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Authentication API](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/endpoints/auth.py): `backend/app/api/v1/endpoints/auth.py`
- [Authentication service](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Device sessions](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/services/session_service.py): `backend/app/services/session_service.py`

### People and operations

- [Employee records](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/models/employee.py): `backend/app/models/employee.py`
- [HR workflows](https://github.com/milad-mma/faipco-portal/tree/main/backend/app/services): `backend/app/services`
- [Notices and payroll](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/endpoints/notices.py): `backend/app/api/v1/endpoints/notices.py`
- [GPS attendance](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/endpoints/attendance.py): `backend/app/api/v1/endpoints/attendance.py`
- [Performance evaluation](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/endpoints/evaluation_process.py): `backend/app/api/v1/endpoints/evaluation_process.py`
- [Office automation](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/endpoints/automation.py): `backend/app/api/v1/endpoints/automation.py`

### Site integrations

- [Employee sync](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/sync_engine/sync_service.py): `backend/app/sync_engine/sync_service.py`
- **Site databases**

### Portal platform

- [Portal database](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Backup and recovery](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/endpoints/backup.py): `backend/app/api/v1/endpoints/backup.py`
- [Web Push](https://github.com/milad-mma/faipco-portal/blob/main/backend/app/api/v1/endpoints/push.py): `backend/app/api/v1/endpoints/push.py`

### Other components

- **Employees**

## Connections

- Employees → React portal: uses (evidence: `README.md`)
- React portal → Portal routes: renders (evidence: `frontend/src/main.jsx`)
- Portal routes → Session context: guards routes (evidence: `frontend/src/App.jsx`)
- Session context → API client: requests identity (evidence: `frontend/src/context/AuthContext.jsx`)
- React portal → API router: calls API (evidence: `README.md`)
- API router → Authentication API: registers (evidence: `backend/app/api/v1/router.py`)
- Authentication API → Authentication service: delegates (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Authentication service → Device sessions: manages sessions (evidence: `backend/app/services/auth_service.py`)
- Authentication service → Portal database: queries
- Employee sync → Site databases: reads employees
- Employee sync → Employee records: synchronizes (evidence: `backend/app/sync_engine/sync_service.py`)
- Employee records → Portal database: stored in (evidence: `backend/app/models/employee.py`)
- Employees → HR workflows: uses (evidence: `README.md`)
- Employees → Notices and payroll: reads notices (evidence: `README.md`)
- Employees → GPS attendance: records attendance (evidence: `README.md`)
- Employees → Performance evaluation: completes evaluations (evidence: `README.md`)
- Employees → Office automation: submits requests (evidence: `README.md`)
- Employees → Backup and recovery: uses administration (evidence: `README.md`)
- Employees → Web Push: receives alerts (evidence: `README.md`)