# pzio-2026/pzio architecture

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

- Interactive diagram: https://gitdiagram.com/pzio-2026/pzio
- Repository: https://github.com/pzio-2026/pzio

## Overview

1. **Overall shape**
   - PZIO is a full-stack Jira-like task management system with a clear split between a Python backend and a React/TypeScript frontend.
   - The backend exposes a JSON API; the frontend is a single-page app that consumes that API.

2. **Backend runtime and core framework**
   - The backend lives under `backend/pzio` and is built with **FastAPI** and **SQLAlchemy**.
   - Startup appears centered around `pzio/main.py`, with shared app configuration in `config.py`, database setup in `db.py`, and a CLI/module entrypoint in `__main__.py`.

3. **Backend module boundaries**
   - The backend is organized into feature modules: **auth**, **admin**, **projects**, **tasks**, and **communication**.
   - Each module typically has its own `router.py`, `service.py`, `models.py`, and `schemas.py`, which suggests a clean layering of:
     - HTTP routing
     - business logic
     - persistence models
     - request/response DTOs

4. **Authentication and authorization flow**
   - The `auth` module handles registration, login, OAuth, password reset, profile management, roles, and security concerns.
   - Authorization is role-based, with roles such as `TeamMember`, `Manager`, and `Administrator`.
   - The README notes a bootstrap rule: the first registered user becomes the administrator, and later users default to team member.

5. **Admin subsystem**
   - The `admin` module provides operational endpoints for system management, including users, activity logs, backups, and task types.
   - This module is distinct from normal project/task workflows and likely exposes privileged functionality for administrators only.

6. **Project and task domain**
   - `projects` models the project-level domain: projects, members, sprints, backlog, and project-specific permissions.
   - `tasks` holds task-level behavior and detail views, likely including task state, assignment, and worklog-related persistence.
   - The frontend structure mirrors this split, which indicates these are the main business entities in the app.

7. **Communication subsystem**
   - `communication` handles task-related collaboration features such as comments, attachments, and notifications.
   - It has a dedicated service layer plus support for message delivery abstractions, including `smtp.py` and `mock.py`, implying pluggable notification transport for real email vs test/mock execution.

8. **Data and persistence**
   - Persistence is database-backed through SQLAlchemy, with SQLite for development and PostgreSQL for production.
   - The app auto-creates its database schema on first run, so there is no manual migration/bootstrap script in the normal startup path.
   - `backend/pzio/modules/projects/seed.py` suggests some domain seed data is loaded for projects or task types.

9. **Frontend runtime and structure**
   - The frontend is a **React + TypeScript** app in `frontend/src`, built with **Vite** and styled with **Tailwind CSS**.
   - It is organized by the same business modules as the backend: `auth`, `projects`, `tasks`, `communication`, and `admin`.
   - Shared app composition lives in components such as `App.tsx`, `AppLayout.tsx`, and `ConfirmProvider.tsx`.

10. **Frontend-to-backend data flow**
   - The frontend uses module-specific API clients under `src/api` and `src/modules/*/api.ts` to call backend endpoints.
   - Pages and components render domain data from those clients, and authenticated state is managed through `AuthProvider`, context/hooks, and local storage helpers.
   - Protected routes enforce login-gated navigation in the client, while backend permissions remain the source of truth.

11. **UI domains and user journeys**
   - Authentication screens cover login, registration, password reset, OAuth callback, and profile editing.
   - Project screens cover list/overview/board/backlog/members/sprints, while task screens focus on task lists and task detail.
   - Admin screens expose operational control panels such as users, backups, task history, and task types.

12. **API documentation and contract**
   - The repository includes generated API documentation in `docs/api/openapi.yaml`.
   - `backend/scripts/dump_openapi.py` indicates the backend OpenAPI spec is exported from the FastAPI app and checked into docs, so the API contract is a first-class artifact.

13. **Development, testing, and deployment**
   - The repo is set up for CI with GitHub Actions for backend pytest and frontend npm builds.
   - Docker Compose runs the full stack with PostgreSQL, backend, and frontend; each service has its own Dockerfile.
   - `backend/README.md` and `frontend/README.md` likely contain component-specific startup details, but the top-level repo is designed for local dev and containerized deployment.

14. **Architecture diagram takeaway**
   - The main diagram should show: browser SPA → frontend API client → FastAPI backend routers → service layer → SQLAlchemy models → database, with a side path for communication/notifications and admin-only operations.
   - The most important boundaries are frontend vs backend, public auth vs privileged admin, and domain modules vs shared infrastructure.

Main entry points: [`backend/pzio/main.py`](https://github.com/pzio-2026/pzio/blob/master/backend/pzio/main.py) (App entry), [`frontend/src/components/App.tsx`](https://github.com/pzio-2026/pzio/blob/master/frontend/src/components/App.tsx) (App shell), [`frontend/src/api/client.ts`](https://github.com/pzio-2026/pzio/blob/master/frontend/src/api/client.ts) (API client), [`backend/pzio/modules/projects/services.py`](https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/projects/services.py) (Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_frontend["Frontend"]
  node_n_browser(("Browser SPA<br/>client<br/>[main.tsx]"))
  node_n_app_shell["App shell<br/>ui composition<br/>[App.tsx]"]
  node_n_auth_ui["Auth UI<br/>frontend module<br/>[LoginPage.tsx]"]
  node_n_projects_ui["Projects UI<br/>frontend module"]
  node_n_tasks_ui["Tasks UI<br/>frontend module<br/>[TaskDetailPage.tsx]"]
  node_n_comm_ui["Comms UI<br/>frontend module"]
  node_n_admin_ui["Admin UI<br/>frontend module<br/>[AdminPanelPage.tsx]"]
  node_n_api_client["API client<br/>frontend data access<br/>[client.ts]"]
end

subgraph group_g_backend["Backend"]
  node_n_main["App entry<br/>fastapi bootstrap<br/>[main.py]"]
  node_n_config_db[("Config & DB<br/>infra<br/>[config.py]")]
  node_n_auth_srv["Auth API<br/>backend module<br/>[router.py]"]
  node_n_projects_srv["Projects API<br/>backend module<br/>[router.py]"]
  node_n_tasks_srv["Tasks API<br/>backend module<br/>[router.py]"]
  node_n_comm_srv["Comm API<br/>backend module<br/>[router.py]"]
  node_n_admin_srv["Admin API<br/>backend module<br/>[router.py]"]
  node_n_services["Services<br/>backend service layer<br/>[services.py]"]
  node_n_models[("Models<br/>[models.py]")]
  node_n_notifications["Notifications<br/>delivery<br/>[smtp.py]"]
end

subgraph group_g_shared["Shared"]
  node_n_openapi["OpenAPI spec<br/>api contract<br/>[openapi.yaml]"]
  node_n_deploy["Compose stack<br/>deployment<br/>[docker-compose.yml]"]
end

node_n_browser -->|"renders"| node_n_app_shell
node_n_app_shell -->|"routes to"| node_n_auth_ui
node_n_app_shell -->|"routes to"| node_n_projects_ui
node_n_app_shell -->|"routes to"| node_n_tasks_ui
node_n_app_shell -->|"routes to"| node_n_comm_ui
node_n_app_shell -->|"routes to"| node_n_admin_ui
node_n_auth_ui -->|"calls"| node_n_api_client
node_n_projects_ui -->|"calls"| node_n_api_client
node_n_tasks_ui -->|"calls"| node_n_api_client
node_n_comm_ui -->|"calls"| node_n_api_client
node_n_admin_ui -->|"calls"| node_n_api_client
node_n_api_client -->|"HTTP JSON"| node_n_main
node_n_main -->|"bootstraps"| node_n_config_db
node_n_main -->|"mounts"| node_n_auth_srv
node_n_main -->|"mounts"| node_n_projects_srv
node_n_main -->|"mounts"| node_n_tasks_srv
node_n_main -->|"mounts"| node_n_comm_srv
node_n_main -->|"mounts"| node_n_admin_srv
node_n_auth_srv -->|"delegates"| node_n_services
node_n_projects_srv -->|"delegates"| node_n_services
node_n_tasks_srv -->|"delegates"| node_n_services
node_n_comm_srv -->|"uses"| node_n_notifications
node_n_admin_srv -->|"delegates"| node_n_services
node_n_services -->|"persists"| node_n_models
node_n_models -->|"stored in"| node_n_config_db
node_n_main -.->|"exports"| node_n_openapi
node_n_deploy -->|"runs"| node_n_main
node_n_deploy -->|"serves"| node_n_browser

click node_n_browser "https://github.com/pzio-2026/pzio/blob/master/frontend/src/main.tsx"
click node_n_app_shell "https://github.com/pzio-2026/pzio/blob/master/frontend/src/components/App.tsx"
click node_n_auth_ui "https://github.com/pzio-2026/pzio/blob/master/frontend/src/modules/auth/pages/LoginPage.tsx"
click node_n_projects_ui "https://github.com/pzio-2026/pzio/blob/master/frontend/src/modules/projects/pages/ProjectsOverviewPage.tsx"
click node_n_tasks_ui "https://github.com/pzio-2026/pzio/blob/master/frontend/src/modules/tasks/pages/TaskDetailPage.tsx"
click node_n_comm_ui "https://github.com/pzio-2026/pzio/blob/master/frontend/src/modules/communication/components/TaskCommunicationPanel.tsx"
click node_n_admin_ui "https://github.com/pzio-2026/pzio/blob/master/frontend/src/modules/admin/pages/AdminPanelPage.tsx"
click node_n_api_client "https://github.com/pzio-2026/pzio/blob/master/frontend/src/api/client.ts"
click node_n_main "https://github.com/pzio-2026/pzio/blob/master/backend/pzio/main.py"
click node_n_config_db "https://github.com/pzio-2026/pzio/blob/master/backend/pzio/config.py"
click node_n_auth_srv "https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/auth/router.py"
click node_n_projects_srv "https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/projects/router.py"
click node_n_tasks_srv "https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/tasks/router.py"
click node_n_comm_srv "https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/communication/router.py"
click node_n_admin_srv "https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/admin/router.py"
click node_n_services "https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/projects/services.py"
click node_n_models "https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/projects/models.py"
click node_n_notifications "https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/communication/smtp.py"
click node_n_openapi "https://github.com/pzio-2026/pzio/blob/master/docs/api/openapi.yaml"
click node_n_deploy "https://github.com/pzio-2026/pzio/blob/master/docker-compose.yml"

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_n_browser,node_n_app_shell,node_n_auth_ui,node_n_projects_ui,node_n_tasks_ui,node_n_comm_ui,node_n_admin_ui,node_n_api_client toneBlue
class node_n_main,node_n_config_db,node_n_auth_srv,node_n_projects_srv,node_n_tasks_srv,node_n_comm_srv,node_n_admin_srv,node_n_services,node_n_models,node_n_notifications toneAmber
class node_n_openapi,node_n_deploy toneMint
```

## Components

### Frontend

React/TypeScript SPA and UI modules

- [Browser SPA](https://github.com/pzio-2026/pzio/blob/master/frontend/src/main.tsx): client · User-facing single-page app · `frontend/src/main.tsx`
- [App shell](https://github.com/pzio-2026/pzio/blob/master/frontend/src/components/App.tsx): ui composition · Top-level layout, providers, and protected routing · `frontend/src/components/App.tsx`
- [Auth UI](https://github.com/pzio-2026/pzio/blob/master/frontend/src/modules/auth/pages/LoginPage.tsx): frontend module · Login, register, profile, and auth state · `frontend/src/modules/auth/pages/LoginPage.tsx`
- [Projects UI](https://github.com/pzio-2026/pzio/blob/master/frontend/src/modules/projects/pages/ProjectsOverviewPage.tsx): frontend module · Project overview, backlog, board, members, and sprints · `frontend/src/modules/projects/pages/ProjectsOverviewPage.tsx`
- [Tasks UI](https://github.com/pzio-2026/pzio/blob/master/frontend/src/modules/tasks/pages/TaskDetailPage.tsx): frontend module · Task list, task detail, and worklog views · `frontend/src/modules/tasks/pages/TaskDetailPage.tsx`
- [Comms UI](https://github.com/pzio-2026/pzio/blob/master/frontend/src/modules/communication/components/TaskCommunicationPanel.tsx): frontend module · Comments, attachments, and collaboration panel · `frontend/src/modules/communication/components/TaskCommunicationPanel.tsx`
- [Admin UI](https://github.com/pzio-2026/pzio/blob/master/frontend/src/modules/admin/pages/AdminPanelPage.tsx): frontend module · Operational panels for users, backups, task types, and history · `frontend/src/modules/admin/pages/AdminPanelPage.tsx`
- [API client](https://github.com/pzio-2026/pzio/blob/master/frontend/src/api/client.ts): frontend data access · Shared client and per-module API adapters · `frontend/src/api/client.ts`

### Backend

FastAPI application, domain modules, and persistence

- [App entry](https://github.com/pzio-2026/pzio/blob/master/backend/pzio/main.py): fastapi bootstrap · Backend application startup and router composition · `backend/pzio/main.py`
- [Config & DB](https://github.com/pzio-2026/pzio/blob/master/backend/pzio/config.py): infra · Settings, database setup, and schema initialization · `backend/pzio/config.py`
- [Auth API](https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/auth/router.py): backend module · Registration, login, OAuth, password reset, roles, and profile · `backend/pzio/modules/auth/router.py`
- [Projects API](https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/projects/router.py): backend module · Projects, members, sprints, backlog, and permissions · `backend/pzio/modules/projects/router.py`
- [Tasks API](https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/tasks/router.py): backend module · Task routing, task details, and task state handling · `backend/pzio/modules/tasks/router.py`
- [Comm API](https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/communication/router.py): backend module · Comments, attachments, notifications, and delivery abstractions · `backend/pzio/modules/communication/router.py`
- [Admin API](https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/admin/router.py): backend module · User administration, activity logs, backups, and task types · `backend/pzio/modules/admin/router.py`
- [Services](https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/projects/services.py): backend service layer · Business logic across feature modules · `backend/pzio/modules/projects/services.py`
- [Models](https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/projects/models.py): sqlalchemy models · Domain persistence models shared by feature modules · `backend/pzio/modules/projects/models.py`
- [Notifications](https://github.com/pzio-2026/pzio/blob/master/backend/pzio/modules/communication/smtp.py): delivery · SMTP and mock notification transport · `backend/pzio/modules/communication/smtp.py`

### Shared

API contract, docs, and deployment assets

- [OpenAPI spec](https://github.com/pzio-2026/pzio/blob/master/docs/api/openapi.yaml): api contract · Generated API documentation exported from FastAPI · `docs/api/openapi.yaml`
- [Compose stack](https://github.com/pzio-2026/pzio/blob/master/docker-compose.yml): deployment · Containerized backend, frontend, and PostgreSQL runtime · `docker-compose.yml`

## Connections

- Browser SPA → App shell: renders · The SPA is composed by the top-level shell
- App shell → Auth UI: routes to · Authentication flows live in the auth module
- App shell → Projects UI: routes to · Project views are mounted through the shell
- App shell → Tasks UI: routes to · Task pages are mounted through the shell
- App shell → Comms UI: routes to · Communication views are embedded in task/project pages
- App shell → Admin UI: routes to · Admin pages are protected by the client router
- Auth UI → API client: calls · Auth forms submit through the API layer
- Projects UI → API client: calls · Project screens load and mutate via API adapters
- Tasks UI → API client: calls · Task screens fetch and update task data via API adapters
- Comms UI → API client: calls · Comment and attachment actions go through the API layer
- Admin UI → API client: calls · Admin panels use backend administration endpoints
- API client → App entry: HTTP JSON · Frontend clients talk to the FastAPI backend
- App entry → Config & DB: bootstraps · Startup loads configuration and database state
- App entry → Auth API: mounts · Auth routes are registered in the app
- App entry → Projects API: mounts · Project routes are registered in the app
- App entry → Tasks API: mounts · Task routes are registered in the app
- App entry → Comm API: mounts · Communication routes are registered in the app
- App entry → Admin API: mounts · Admin routes are registered in the app
- Auth API → Services: delegates · Auth routing delegates to business logic
- Projects API → Services: delegates · Project routing delegates to business logic
- Tasks API → Services: delegates · Task routing delegates to business logic
- Comm API → Notifications: uses · Communication service sends via SMTP or mock transports
- Admin API → Services: delegates · Admin operations reuse service-layer logic
- Services → Models: persists · Business logic reads and writes SQLAlchemy models
- Models → Config & DB: stored in · Domain state is backed by the configured database
- App entry → OpenAPI spec: exports · The FastAPI app is the source of the published contract
- Compose stack → App entry: runs · Compose starts the backend service
- Compose stack → Browser SPA: serves · Compose includes the frontend runtime
