How eagleeye-2022/winos works
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: schema.prisma Prisma DB · action-utils.ts Action guards · auth.ts Auth runtime · layout.tsx Dashboard layout
Components 23
Routing
App Router boundaries, layouts, and request entrypoints
- App shell · Top-level app layout and global styles
src/app/layout.tsx - Auth layout · Shared layout for login flow
src/app/(auth)/layout.tsx - Login page · Entry page for passwordless sign-in
src/app/(auth)/login/page.tsx - Dashboard layout · Logged-in shell for operational workflows
src/app/(dashboard)/layout.tsx - Home page · Landing page after authentication
src/app/(dashboard)/dashboard/page.tsx - Auth API · NextAuth/Auth.js endpoint
src/app/api/auth/[...nextauth]/route.ts - DB health · Database health and debug endpoint
src/app/api/debug/db-health/route.ts - Proxy guard · Request-level access control before dashboard routes
proxy.ts
Features
Domain modules for workflows, actions, queries, and guards
- Auth flow · OTP login/logout, session handling, and auth UI
src/features/auth/index.ts - DSM · Morning standup capture and review workflow
src/features/dsm/index.ts - DSM manager · Manager review, team setup, priorities, and reminders
src/features/dsm/manager/queries.ts - DSR · End-of-day review workflow and follow-ups
src/features/dsr/queries.ts - DSR manager · Manager review and prioritization for DSR submissions
src/features/dsr/manager/queries.ts - Notes · Personal notebooks, tags, checklist items, and pinning
src/features/notes/index.ts - Blockers · Team-visible blockers, comments, resolution, and reminders
src/features/blockers/queries.ts - Support · Support-needed items with comments, reminders, and resolution
src/features/support-needed/queries.ts - Needs help · Unresolved help requests and resolution tracking
src/features/needs-help/queries.ts - Notifications · Notification storage, read state, and bell UI
src/features/notifications/queries.ts
Platform
Shared runtime services, persistence, and request/session infrastructure
- Shared UI · Cross-feature shell components and dashboard chrome
src/components/shared/app-sidebar.tsx - Prisma DB · Prisma schema and PostgreSQL-backed system of record
prisma/schema.prisma - Auth runtime · Passwordless OTP, sessions, and auth helpers
src/lib/auth.ts - Mail layer · SMTP/Nodemailer delivery for OTPs and reminders
src/lib/email.ts - Action guards · Shared validation, permission, and submission guard utilities
src/lib/action-utils.ts
Connections 30
- 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