# eagleeye-2022/winos architecture

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

- Interactive diagram: https://gitdiagram.com/eagleeye-2022/winos
- Repository: https://github.com/eagleeye-2022/winos

## Overview

1. **Overall shape**
   - WinOS is a **Next.js 16 App Router** application with a mostly server-driven architecture.
   - The app is split into **auth pages** and a **dashboard shell** for the operational workflows.
   - Business logic is organized by domain under `src/features/*`, rather than by generic controller/service layers.

2. **Primary runtime boundaries**
   - **Browser UI** uses React components, many of which are client components for interactivity.
   - **Server actions** in `src/features/**/actions` are the main write path for user operations.
   - **Prisma/PostgreSQL** is the system of record for users, standups, notes, blockers, support items, and notifications.
   - **Auth.js / NextAuth** handles login state and session management.
   - **Nodemailer + SMTP** is used only for OTP delivery and reminders.

3. **Routing and page layout**
   - `src/app/(auth)` contains the login flow and shared auth layout.
   - `src/app/(dashboard)` contains all logged-in workflows: dashboard, DSM, DSR, notes, blockers, support, and needs-help.
   - `src/app/api/auth/[...nextauth]` exposes the auth endpoint, while `src/app/api/debug/db-health` provides a DB health/debug route.
   - `proxy.ts` is the request-level boundary that likely enforces auth/access behavior before dashboard routes are reached.

4. **Identity and access model**
   - Authentication is **passwordless OTP**: users request a 6-digit code, then verify it to establish a session.
   - Only pre-provisioned `@eagleeyedigital.io` users exist in the database.
   - The app distinguishes two roles: **TEAM_MEMBER** and **MANAGER**.
   - Role checks are enforced in feature utilities and action guards, especially for manager-only review and team administration paths.

5. **Core data model**
   - Prisma defines the main entities: `User`, `Account`, `Session`, `OtpToken`, `VerificationToken`, `Team`, `TeamMember`.
   - Operational records include `StandupEntry`, `StandupTask`, `StandupBlocker`, `StandupSupportNeed`, `DsrEntry`, `DsrPlannedTask`, `DsrResolvedBlocker`, `DsrFollowUpDone`, `DsrTimelineEvent`.
   - Collaboration/coordination entities include `Notification`, `Note`, `Notebook`, `Tag`, `ChecklistItem`, `Blocker`, and support-related records.
   - This schema is the central integration point for all feature modules.

6. **DSM subsystem**
   - DSM is the morning standup workflow: yesterday’s work, today’s plan, blockers, and support needs.
   - Team members submit through DSM form components; server actions persist entries and related task/blocker/support rows.
   - Managers use DSM manager screens to review submissions, assign priorities, update team data, and send reminders.
   - DSM reads are split between personal views (`my`) and manager views (`all`, `member/[userId]`).

7. **DSR subsystem**
   - DSR is the end-of-day review workflow with completion tracking, sentiment/reflection, and follow-up data.
   - Team members submit through DSR forms; server actions save the review and related follow-up entities.
   - Managers review DSR submissions through manager pages and can mark items reviewed or adjust priorities.
   - As with DSM, the read path is separated into self views and manager views.

8. **Notes subsystem**
   - Notes are personal knowledge items organized into notebooks and tags, with checklist support and pinning.
   - The notes feature has its own actions for create/update/delete, notebook creation, checklist toggles, and pin state.
   - This subsystem is user-scoped rather than team-wide, but still lives in the same shared auth/database boundary.

9. **Blockers, support, and needs-help**
   - Blockers and support-needed items are team-visible coordination objects with comment, reminder, and resolution actions.
   - `needs-help` is a separate dashboard surface for unresolved help requests and resolution tracking.
   - These features share a common pattern: list/query components for reads, server actions for state transitions, and permission utilities for who can modify or resolve items.

10. **Notifications and reminders**
    - `src/features/notifications` stores and renders in-app notifications, including read/unread state.
    - Reminder actions are used by managers to trigger follow-ups, and some workflows send emails via the shared mail layer.
    - The notification bell in the UI is the primary surface for consuming this stream.

11. **UI composition**
    - `src/components/shared` contains cross-feature shell elements like the sidebar, clock chip, color picker, and delete confirmation bar.
    - Feature-specific client components compose those shared pieces into dashboards, cards, forms, and review panels.
    - The app uses Tailwind CSS and shared UI primitives, but the architectural separation is by domain feature rather than by generic component library.

12. **Supporting infrastructure and operations**
    - PostgreSQL is expected in every environment; local dev uses a Prisma-managed database flow documented in `docs/local-db-debugging.md`.
    - The repo includes scripts for starting/resetting the local DB, seeding, DB push, smoke checks, and screenshot verification.
    - CI runs `prisma generate`, lint, tests, and build via GitHub Actions.
    - Production deployment is via **AWS Amplify Hosting with SSR compute**, with environment variables injected at build time.

13. **Testing and quality gates**
    - Unit tests focus on feature utilities, permission logic, OTP behavior, and submission guards.
    - The test suite reinforces the architectural boundaries by validating server-side rules separately from UI rendering.
    - This is important for the diagram because most business rules live outside the page components, in feature utilities and server actions.

14. **Key end-to-end data flows**
    - **Login flow:** browser submits email → NextAuth/Auth.js issues OTP → email or console delivery → OTP verification creates session → dashboard access.
    - **Submit flow:** dashboard form → server action → Prisma writes to Postgres → updated query data re-renders the relevant page.
    - **Manager flow:** manager dashboard/page → query reads team data → action updates priorities/reviews/reminders → notifications and/or email reminders may be emitted.

Main entry points: [`prisma/schema.prisma`](https://github.com/eagleeye-2022/winos/blob/main/prisma/schema.prisma) (Prisma DB), [`src/lib/action-utils.ts`](https://github.com/eagleeye-2022/winos/blob/main/src/lib/action-utils.ts) (Action guards), [`src/lib/auth.ts`](https://github.com/eagleeye-2022/winos/blob/main/src/lib/auth.ts) (Auth runtime), [`src/app/(dashboard)/layout.tsx`](https://github.com/eagleeye-2022/winos/blob/main/src/app/(dashboard)/layout.tsx) (Dashboard layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Routing"]
  node_app_root["App shell<br/>nextjs app<br/>[layout.tsx]"]
  node_auth_layout["Auth layout<br/>route layout<br/>[layout.tsx]"]
  node_login_page["Login page<br/>auth route<br/>[page.tsx]"]
  node_dashboard_layout["Dashboard layout<br/>route layout<br/>[layout.tsx]"]
  node_dashboard_home["Home page<br/>dashboard route<br/>[page.tsx]"]
  node_api_auth["Auth API<br/>route handler<br/>[route.ts]"]
  node_api_db_health["DB health<br/>debug route<br/>[route.ts]"]
  node_proxy_boundary["Proxy guard<br/>request boundary<br/>[proxy.ts]"]
end

subgraph group_features["Features"]
  node_auth_feature["Auth flow<br/>feature module<br/>[index.ts]"]
  node_dsm_feature["DSM<br/>feature module<br/>[index.ts]"]
  node_dsm_manager["DSM manager<br/>manager module<br/>[queries.ts]"]
  node_dsr_feature["DSR<br/>feature module<br/>[queries.ts]"]
  node_dsr_manager["DSR manager<br/>manager module<br/>[queries.ts]"]
  node_notes_feature["Notes<br/>feature module<br/>[index.ts]"]
  node_blockers_feature["Blockers<br/>coordination feature<br/>[queries.ts]"]
  node_support_feature["Support<br/>coordination feature<br/>[queries.ts]"]
  node_needs_help_feature["Needs help<br/>triage feature<br/>[queries.ts]"]
  node_notifications_feature["Notifications<br/>in-app stream<br/>[queries.ts]"]
end

subgraph group_platform["Platform"]
  node_shared_ui["Shared UI<br/>ui components<br/>[app-sidebar.tsx]"]
  node_db_layer[("Prisma DB<br/>persistence layer<br/>[schema.prisma]")]
  node_auth_runtime["Auth runtime<br/>session+otp<br/>[auth.ts]"]
  node_mail_layer["Mail layer<br/>email service<br/>[email.ts]"]
  node_action_utils["Action guards<br/>server-action helpers<br/>[action-utils.ts]"]
end

node_app_root -->|"renders"| node_auth_layout
node_app_root -->|"renders"| node_dashboard_layout
node_auth_layout -->|"hosts"| node_login_page
node_dashboard_layout -->|"hosts"| node_dashboard_home
node_login_page -->|"uses"| node_auth_feature
node_api_auth -->|"delegates"| node_auth_runtime
node_auth_feature -->|"calls"| node_auth_runtime
node_auth_runtime -->|"reads/writes"| node_db_layer
node_auth_runtime -->|"sends"| node_mail_layer
node_dashboard_layout -->|"protected by"| node_proxy_boundary
node_dashboard_home -->|"composes"| node_shared_ui
node_dashboard_home -->|"shows"| node_notifications_feature
node_dsm_feature -->|"persists to"| node_db_layer
node_dsm_manager -->|"reviews"| node_db_layer
node_dsr_feature -->|"persists to"| node_db_layer
node_dsr_manager -->|"reviews"| node_db_layer
node_notes_feature -->|"persists to"| node_db_layer
node_blockers_feature -->|"persists to"| node_db_layer
node_support_feature -->|"persists to"| node_db_layer
node_needs_help_feature -->|"persists to"| node_db_layer
node_notifications_feature -->|"reads/writes"| node_db_layer
node_dsm_feature -->|"guards"| node_action_utils
node_dsm_manager -->|"guards"| node_action_utils
node_dsr_feature -->|"guards"| node_action_utils
node_dsr_manager -->|"guards"| node_action_utils
node_blockers_feature -->|"guards"| node_action_utils
node_support_feature -->|"guards"| node_action_utils
node_notifications_feature -->|"triggers"| node_mail_layer
node_api_db_health -->|"probes"| node_db_layer
node_proxy_boundary -->|"checks"| node_auth_runtime

click node_app_root "https://github.com/eagleeye-2022/winos/blob/main/src/app/layout.tsx"
click node_auth_layout "https://github.com/eagleeye-2022/winos/blob/main/src/app/(auth)/layout.tsx"
click node_login_page "https://github.com/eagleeye-2022/winos/blob/main/src/app/(auth)/login/page.tsx"
click node_dashboard_layout "https://github.com/eagleeye-2022/winos/blob/main/src/app/(dashboard)/layout.tsx"
click node_dashboard_home "https://github.com/eagleeye-2022/winos/blob/main/src/app/(dashboard)/dashboard/page.tsx"
click node_api_auth "https://github.com/eagleeye-2022/winos/blob/main/src/app/api/auth/[...nextauth]/route.ts"
click node_api_db_health "https://github.com/eagleeye-2022/winos/blob/main/src/app/api/debug/db-health/route.ts"
click node_proxy_boundary "https://github.com/eagleeye-2022/winos/blob/main/proxy.ts"
click node_auth_feature "https://github.com/eagleeye-2022/winos/blob/main/src/features/auth/index.ts"
click node_dsm_feature "https://github.com/eagleeye-2022/winos/blob/main/src/features/dsm/index.ts"
click node_dsm_manager "https://github.com/eagleeye-2022/winos/blob/main/src/features/dsm/manager/queries.ts"
click node_dsr_feature "https://github.com/eagleeye-2022/winos/blob/main/src/features/dsr/queries.ts"
click node_dsr_manager "https://github.com/eagleeye-2022/winos/blob/main/src/features/dsr/manager/queries.ts"
click node_notes_feature "https://github.com/eagleeye-2022/winos/blob/main/src/features/notes/index.ts"
click node_blockers_feature "https://github.com/eagleeye-2022/winos/blob/main/src/features/blockers/queries.ts"
click node_support_feature "https://github.com/eagleeye-2022/winos/blob/main/src/features/support-needed/queries.ts"
click node_needs_help_feature "https://github.com/eagleeye-2022/winos/blob/main/src/features/needs-help/queries.ts"
click node_notifications_feature "https://github.com/eagleeye-2022/winos/blob/main/src/features/notifications/queries.ts"
click node_shared_ui "https://github.com/eagleeye-2022/winos/blob/main/src/components/shared/app-sidebar.tsx"
click node_db_layer "https://github.com/eagleeye-2022/winos/blob/main/prisma/schema.prisma"
click node_auth_runtime "https://github.com/eagleeye-2022/winos/blob/main/src/lib/auth.ts"
click node_mail_layer "https://github.com/eagleeye-2022/winos/blob/main/src/lib/email.ts"
click node_action_utils "https://github.com/eagleeye-2022/winos/blob/main/src/lib/action-utils.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_app_root,node_auth_layout,node_login_page,node_dashboard_layout,node_dashboard_home,node_api_auth,node_api_db_health,node_proxy_boundary toneBlue
class node_auth_feature,node_dsm_feature,node_dsm_manager,node_dsr_feature,node_dsr_manager,node_notes_feature,node_blockers_feature,node_support_feature,node_needs_help_feature,node_notifications_feature toneAmber
class node_shared_ui,node_db_layer,node_auth_runtime,node_mail_layer,node_action_utils toneMint
```

## Components

### Routing

App Router boundaries, layouts, and request entrypoints

- [App shell](https://github.com/eagleeye-2022/winos/blob/main/src/app/layout.tsx): nextjs app · Top-level app layout and global styles · `src/app/layout.tsx`
- [Auth layout](https://github.com/eagleeye-2022/winos/blob/main/src/app/(auth)/layout.tsx): route layout · Shared layout for login flow · `src/app/(auth)/layout.tsx`
- [Login page](https://github.com/eagleeye-2022/winos/blob/main/src/app/(auth)/login/page.tsx): auth route · Entry page for passwordless sign-in · `src/app/(auth)/login/page.tsx`
- [Dashboard layout](https://github.com/eagleeye-2022/winos/blob/main/src/app/(dashboard)/layout.tsx): route layout · Logged-in shell for operational workflows · `src/app/(dashboard)/layout.tsx`
- [Home page](https://github.com/eagleeye-2022/winos/blob/main/src/app/(dashboard)/dashboard/page.tsx): dashboard route · Landing page after authentication · `src/app/(dashboard)/dashboard/page.tsx`
- [Auth API](https://github.com/eagleeye-2022/winos/blob/main/src/app/api/auth/[...nextauth]/route.ts): route handler · NextAuth/Auth.js endpoint · `src/app/api/auth/[...nextauth]/route.ts`
- [DB health](https://github.com/eagleeye-2022/winos/blob/main/src/app/api/debug/db-health/route.ts): debug route · Database health and debug endpoint · `src/app/api/debug/db-health/route.ts`
- [Proxy guard](https://github.com/eagleeye-2022/winos/blob/main/proxy.ts): request boundary · Request-level access control before dashboard routes · `proxy.ts`

### Features

Domain modules for workflows, actions, queries, and guards

- [Auth flow](https://github.com/eagleeye-2022/winos/blob/main/src/features/auth/index.ts): feature module · OTP login/logout, session handling, and auth UI · `src/features/auth/index.ts`
- [DSM](https://github.com/eagleeye-2022/winos/blob/main/src/features/dsm/index.ts): feature module · Morning standup capture and review workflow · `src/features/dsm/index.ts`
- [DSM manager](https://github.com/eagleeye-2022/winos/blob/main/src/features/dsm/manager/queries.ts): manager module · Manager review, team setup, priorities, and reminders · `src/features/dsm/manager/queries.ts`
- [DSR](https://github.com/eagleeye-2022/winos/blob/main/src/features/dsr/queries.ts): feature module · End-of-day review workflow and follow-ups · `src/features/dsr/queries.ts`
- [DSR manager](https://github.com/eagleeye-2022/winos/blob/main/src/features/dsr/manager/queries.ts): manager module · Manager review and prioritization for DSR submissions · `src/features/dsr/manager/queries.ts`
- [Notes](https://github.com/eagleeye-2022/winos/blob/main/src/features/notes/index.ts): feature module · Personal notebooks, tags, checklist items, and pinning · `src/features/notes/index.ts`
- [Blockers](https://github.com/eagleeye-2022/winos/blob/main/src/features/blockers/queries.ts): coordination feature · Team-visible blockers, comments, resolution, and reminders · `src/features/blockers/queries.ts`
- [Support](https://github.com/eagleeye-2022/winos/blob/main/src/features/support-needed/queries.ts): coordination feature · Support-needed items with comments, reminders, and resolution · `src/features/support-needed/queries.ts`
- [Needs help](https://github.com/eagleeye-2022/winos/blob/main/src/features/needs-help/queries.ts): triage feature · Unresolved help requests and resolution tracking · `src/features/needs-help/queries.ts`
- [Notifications](https://github.com/eagleeye-2022/winos/blob/main/src/features/notifications/queries.ts): in-app stream · Notification storage, read state, and bell UI · `src/features/notifications/queries.ts`

### Platform

Shared runtime services, persistence, and request/session infrastructure

- [Shared UI](https://github.com/eagleeye-2022/winos/blob/main/src/components/shared/app-sidebar.tsx): ui components · Cross-feature shell components and dashboard chrome · `src/components/shared/app-sidebar.tsx`
- [Prisma DB](https://github.com/eagleeye-2022/winos/blob/main/prisma/schema.prisma): persistence layer · Prisma schema and PostgreSQL-backed system of record · `prisma/schema.prisma`
- [Auth runtime](https://github.com/eagleeye-2022/winos/blob/main/src/lib/auth.ts): session+otp · Passwordless OTP, sessions, and auth helpers · `src/lib/auth.ts`
- [Mail layer](https://github.com/eagleeye-2022/winos/blob/main/src/lib/email.ts): email service · SMTP/Nodemailer delivery for OTPs and reminders · `src/lib/email.ts`
- [Action guards](https://github.com/eagleeye-2022/winos/blob/main/src/lib/action-utils.ts): server-action helpers · Shared validation, permission, and submission guard utilities · `src/lib/action-utils.ts`

## Connections

- App shell → Auth layout: renders · Global app shell wraps the auth experience
- App shell → Dashboard layout: renders · Global app shell wraps the logged-in shell
- Auth layout → Login page: hosts · Shared auth layout contains the login page
- Dashboard layout → Home page: hosts · Dashboard layout contains the main landing page
- Login page → Auth flow: uses · Login UI is implemented by the auth feature
- Auth API → Auth runtime: delegates · NextAuth endpoint is backed by auth/session logic
- Auth flow → Auth runtime: calls · Login and logout actions use session helpers and OTP flow
- Auth runtime → Prisma DB: reads/writes · Users, sessions, and OTP tokens are persisted in Postgres
- Auth runtime → Mail layer: sends · OTP codes and auth emails use the mail layer
- Dashboard layout → Proxy guard: protected by · Dashboard routes are gated at the request boundary
- Home page → Shared UI: composes · Dashboard page is built from shared shell components
- Home page → Notifications: shows · Notification bell is part of the dashboard surface
- DSM → Prisma DB: persists to · Standup entries, tasks, blockers, and support needs are stored in Prisma
- DSM manager → Prisma DB: reviews · Manager views read and update team standup data
- DSR → Prisma DB: persists to · DSR submissions and follow-up entities are stored in Prisma
- DSR manager → Prisma DB: reviews · Manager views read and update DSR data
- Notes → Prisma DB: persists to · Notes, notebooks, tags, and checklist state live in the database
- Blockers → Prisma DB: persists to · Blocker records and comments are stored centrally
- Support → Prisma DB: persists to · Support-needed records and comments are stored centrally
- Needs help → Prisma DB: persists to · Help requests and resolution state are stored centrally
- Notifications → Prisma DB: reads/writes · Notification state and delivery markers are persisted
- DSM → Action guards: guards · Submission rules and permissions are enforced before writes
- DSM manager → Action guards: guards · Manager-only update paths use shared action guard logic
- DSR → Action guards: guards · Review submission rules are enforced server-side
- DSR manager → Action guards: guards · Manager review actions use shared permission checks
- Blockers → Action guards: guards · Blocker mutation paths use shared permission checks
- Support → Action guards: guards · Support mutation paths use shared permission checks
- Notifications → Mail layer: triggers · Reminder flows may emit email through the shared mail layer
- DB health → Prisma DB: probes · Debug route checks database connectivity
- Proxy guard → Auth runtime: checks · Request guard depends on session state
