# dev-michaeljohn/my-app architecture

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

- Interactive diagram: https://gitdiagram.com/dev-michaeljohn/my-app
- Repository: https://github.com/dev-michaeljohn/my-app

## Overview

PIT-FES is an academic evaluation platform: users sign in, manage institutional records and class rosters, configure evaluation instruments and schedules, submit evaluations, and review reports and analytics. The frontend routes role- and permission-specific pages; the backend exposes versioned API routes backed by controllers and services. Shared schemas and types define cross-app domain contracts. The sampled evidence confirms app/router wiring and selected module references, but not most controller-to-service calls or frontend HTTP-to-backend links; those links are therefore omitted or marked unverified.

Main entry points: [`apps/frontend/src/app/AppRoutes.tsx`](https://github.com/dev-michaeljohn/my-app/blob/main/apps/frontend/src/app/AppRoutes.tsx) (App routes), [`apps/backend/src/routers/index.router.ts`](https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/routers/index.router.ts) (Versioned routes), [`apps/backend/src/services/user.service.ts`](https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/services/user.service.ts) (Accounts and roles), [`apps/backend/src/app.ts`](https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/app.ts) (HTTP application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_routes["App routes<br/>[AppRoutes.tsx]"]
  node_authui["Authentication UI"]
  node_dashboard["Dashboards"]
  node_academicui["Academic admin UI"]
  node_evaluationui["Evaluation UI"]
  node_analyticsui["Analytics UI"]
  node_usersui["User management UI"]
  node_api_lib["API client<br/>[api.lib.ts]"]
end

subgraph group_api["Backend API"]
  node_backend["HTTP application<br/>[app.ts]"]
  node_v1["Versioned routes<br/>[index.router.ts]"]
  node_authsvc["Authentication services<br/>[auth.service.ts]"]
  node_evaluation_routes["Evaluation endpoints"]
  node_evaluation_services["Evaluation processing"]
  node_analytics_services["Analytics processing"]
  node_logger["Logging<br/>[logger.lib.ts]"]
end

subgraph group_domain["Academic operations"]
  node_institution["Institution records<br/>[college.service.ts]"]
  node_user_services["Accounts and roles<br/>[user.service.ts]"]
  node_communications["Email and OTP<br/>[email.service.ts]"]
  node_realtime["Live updates<br/>[socket.lib.ts]"]
end

subgraph group_contracts["Shared contracts"]
  node_shared_auth["Auth schemas<br/>[auth.schema.ts]"]
  node_shared_institution["Institution schemas"]
  node_shared_eval["Evaluation contracts"]
  node_shared_user["User types<br/>[user.type.ts]"]
end

node_user(("Staff / learner"))

node_user -->|"opens pages"| node_routes
node_routes -->|"routes login"| node_authui
node_routes -->|"routes dashboard"| node_dashboard
node_routes -->|"routes admin"| node_academicui
node_routes -->|"routes evaluations"| node_evaluationui
node_routes -.->|"routes analytics"| node_analyticsui
node_routes -.->|"routes user admin"| node_usersui
node_backend -->|"mounts API"| node_v1
node_v1 -->|"mounts endpoint"| node_evaluation_routes
node_v1 -->|"mounts auth routes"| node_authsvc
node_v1 -->|"mounts academic routes"| node_institution
node_evaluation_routes -.->|"dispatches processing"| node_evaluation_services
node_api_lib -.->|"sends API requests"| node_backend
node_authsvc -->|"uses account service"| node_user_services
node_authsvc -->|"uses OTP service"| node_communications
node_user_services -->|"uses email service"| node_communications
node_institution -->|"uses account service"| node_user_services
node_institution -->|"uses domain schema"| node_shared_institution
node_user_services -->|"uses user types"| node_shared_user
node_evaluationui -.->|"uses evaluation contracts"| node_shared_eval
node_authui -->|"uses auth types"| node_shared_auth
node_logger -->|"streams logs"| node_realtime
node_backend -->|"logs requests"| node_logger
node_v1 -->|"mounts analytics routes"| node_analytics_services

click node_routes "https://github.com/dev-michaeljohn/my-app/blob/main/apps/frontend/src/app/AppRoutes.tsx"
click node_authui "https://github.com/dev-michaeljohn/my-app/tree/main/apps/frontend/src/features/auth"
click node_dashboard "https://github.com/dev-michaeljohn/my-app/tree/main/apps/frontend/src/features/dashboard"
click node_academicui "https://github.com/dev-michaeljohn/my-app/tree/main/apps/frontend/src/features"
click node_evaluationui "https://github.com/dev-michaeljohn/my-app/tree/main/apps/frontend/src/features/evaluations"
click node_analyticsui "https://github.com/dev-michaeljohn/my-app/tree/main/apps/frontend/src/features/analytics"
click node_usersui "https://github.com/dev-michaeljohn/my-app/tree/main/apps/frontend/src/features/users"
click node_api_lib "https://github.com/dev-michaeljohn/my-app/blob/main/apps/frontend/src/lib/api.lib.ts"
click node_backend "https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/app.ts"
click node_v1 "https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/routers/index.router.ts"
click node_authsvc "https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/services/auth.service.ts"
click node_evaluation_routes "https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/routers/evaluation-builder.router.ts"
click node_evaluation_services "https://github.com/dev-michaeljohn/my-app/tree/main/apps/backend/src/services"
click node_analytics_services "https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/services/analytics.service.ts"
click node_institution "https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/services/college.service.ts"
click node_user_services "https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/services/user.service.ts"
click node_communications "https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/services/email.service.ts"
click node_realtime "https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/libs/socket.lib.ts"
click node_shared_auth "https://github.com/dev-michaeljohn/my-app/blob/main/packages/shared/src/schemas/auth.schema.ts"
click node_shared_institution "https://github.com/dev-michaeljohn/my-app/blob/main/packages/shared/src/schemas/institution.schema.ts"
click node_shared_eval "https://github.com/dev-michaeljohn/my-app/blob/main/packages/shared/src/schemas/evaluation-instrument.schema.ts"
click node_shared_user "https://github.com/dev-michaeljohn/my-app/blob/main/packages/shared/src/types/user.type.ts"
click node_logger "https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/libs/logger.lib.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_routes,node_authui,node_dashboard,node_academicui,node_evaluationui,node_analyticsui,node_usersui,node_api_lib toneBlue
class node_backend,node_v1,node_authsvc,node_evaluation_routes,node_evaluation_services,node_analytics_services,node_logger toneAmber
class node_institution,node_user_services,node_communications,node_realtime toneMint
class node_shared_auth,node_shared_institution,node_shared_eval,node_shared_user toneRose
class node_user toneIndigo
```

## Components

### Web client

- [App routes](https://github.com/dev-michaeljohn/my-app/blob/main/apps/frontend/src/app/AppRoutes.tsx): `apps/frontend/src/app/AppRoutes.tsx`
- [Authentication UI](https://github.com/dev-michaeljohn/my-app/tree/main/apps/frontend/src/features/auth): `apps/frontend/src/features/auth`
- [Dashboards](https://github.com/dev-michaeljohn/my-app/tree/main/apps/frontend/src/features/dashboard): `apps/frontend/src/features/dashboard`
- [Academic admin UI](https://github.com/dev-michaeljohn/my-app/tree/main/apps/frontend/src/features): `apps/frontend/src/features`
- [Evaluation UI](https://github.com/dev-michaeljohn/my-app/tree/main/apps/frontend/src/features/evaluations): `apps/frontend/src/features/evaluations`
- [Analytics UI](https://github.com/dev-michaeljohn/my-app/tree/main/apps/frontend/src/features/analytics): `apps/frontend/src/features/analytics`
- [User management UI](https://github.com/dev-michaeljohn/my-app/tree/main/apps/frontend/src/features/users): `apps/frontend/src/features/users`
- [API client](https://github.com/dev-michaeljohn/my-app/blob/main/apps/frontend/src/lib/api.lib.ts): `apps/frontend/src/lib/api.lib.ts`

### Backend API

- [HTTP application](https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/app.ts): `apps/backend/src/app.ts`
- [Versioned routes](https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/routers/index.router.ts): `apps/backend/src/routers/index.router.ts`
- [Authentication services](https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/services/auth.service.ts): `apps/backend/src/services/auth.service.ts`
- [Evaluation endpoints](https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/routers/evaluation-builder.router.ts): `apps/backend/src/routers/evaluation-builder.router.ts`
- [Evaluation processing](https://github.com/dev-michaeljohn/my-app/tree/main/apps/backend/src/services): `apps/backend/src/services`
- [Analytics processing](https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/services/analytics.service.ts): `apps/backend/src/services/analytics.service.ts`
- [Logging](https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/libs/logger.lib.ts): `apps/backend/src/libs/logger.lib.ts`

### Academic operations

- [Institution records](https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/services/college.service.ts): `apps/backend/src/services/college.service.ts`
- [Accounts and roles](https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/services/user.service.ts): `apps/backend/src/services/user.service.ts`
- [Email and OTP](https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/services/email.service.ts): `apps/backend/src/services/email.service.ts`
- [Live updates](https://github.com/dev-michaeljohn/my-app/blob/main/apps/backend/src/libs/socket.lib.ts): `apps/backend/src/libs/socket.lib.ts`

### Shared contracts

- [Auth schemas](https://github.com/dev-michaeljohn/my-app/blob/main/packages/shared/src/schemas/auth.schema.ts): `packages/shared/src/schemas/auth.schema.ts`
- [Institution schemas](https://github.com/dev-michaeljohn/my-app/blob/main/packages/shared/src/schemas/institution.schema.ts): `packages/shared/src/schemas/institution.schema.ts`
- [Evaluation contracts](https://github.com/dev-michaeljohn/my-app/blob/main/packages/shared/src/schemas/evaluation-instrument.schema.ts): `packages/shared/src/schemas/evaluation-instrument.schema.ts`
- [User types](https://github.com/dev-michaeljohn/my-app/blob/main/packages/shared/src/types/user.type.ts): `packages/shared/src/types/user.type.ts`

### Other components

- **Staff / learner**

## Connections

- Staff / learner → App routes: opens pages (evidence: `apps/frontend/src/app/AppRoutes.tsx`)
- App routes → Authentication UI: routes login (evidence: `apps/frontend/src/app/AppRoutes.tsx`)
- App routes → Dashboards: routes dashboard (evidence: `apps/frontend/src/app/AppRoutes.tsx`)
- App routes → Academic admin UI: routes admin (evidence: `apps/frontend/src/app/AppRoutes.tsx`)
- App routes → Evaluation UI: routes evaluations (evidence: `apps/frontend/src/app/AppRoutes.tsx`)
- App routes → Analytics UI: routes analytics
- App routes → User management UI: routes user admin
- HTTP application → Versioned routes: mounts API (evidence: `apps/backend/src/app.ts`)
- Versioned routes → Evaluation endpoints: mounts endpoint (evidence: `apps/backend/src/routers/index.router.ts`)
- Versioned routes → Authentication services: mounts auth routes (evidence: `apps/backend/src/routers/index.router.ts`)
- Versioned routes → Institution records: mounts academic routes (evidence: `apps/backend/src/routers/index.router.ts`)
- Evaluation endpoints → Evaluation processing: dispatches processing
- API client → HTTP application: sends API requests
- Authentication services → Accounts and roles: uses account service (evidence: `apps/backend/src/services/auth.service.ts`)
- Authentication services → Email and OTP: uses OTP service (evidence: `apps/backend/src/services/auth.service.ts`)
- Accounts and roles → Email and OTP: uses email service (evidence: `apps/backend/src/services/user.service.ts`)
- Institution records → Accounts and roles: uses account service (evidence: `apps/backend/src/services/college.service.ts`)
- Institution records → Institution schemas: uses domain schema (evidence: `apps/backend/src/services/college.service.ts`)
- Accounts and roles → User types: uses user types (evidence: `apps/backend/src/services/user.service.ts`)
- Evaluation UI → Evaluation contracts: uses evaluation contracts
- Authentication UI → Auth schemas: uses auth types (evidence: `apps/frontend/src/features/auth/hooks/useAuth.ts`)
- Logging → Live updates: streams logs (evidence: `apps/backend/src/libs/logger.lib.ts`)
- HTTP application → Logging: logs requests (evidence: `apps/backend/src/app.ts`)
- Versioned routes → Analytics processing: mounts analytics routes (evidence: `apps/backend/src/routers/index.router.ts`)
