# yashhhyb/weekly-planerz architecture

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

- Interactive diagram: https://gitdiagram.com/yashhhyb/weekly-planerz
- Repository: https://github.com/yashhhyb/weekly-planerz

## Overview

1. Weekly Planerz is split into a TypeScript Angular frontend and an ASP.NET Core 8 backend, with architecture intentionally kept in separate repository folders. The backend uses Clean Architecture / CQRS-style layering; the frontend is a feature-based SPA with route modules, services, and NgRx-like state slices.

2. The backend request path starts in `WeeklyPlanner.API` controllers: `Backlog`, `Planning`, `Team`, and `Admin`. These controllers expose the REST API and wrap responses in a consistent `ApiResponse` shape, while `GlobalExceptionMiddleware` centralizes error handling before responses leave the API boundary.

3. The application layer (`WeeklyPlanner.Application`) is the orchestration boundary. It contains commands, queries, DTOs, validators, and a MediatR validation behavior. This is where request intent is translated into use-case operations and where FluentValidation checks are applied before handlers run.

4. The domain layer (`WeeklyPlanner.Domain`) holds the core business model: `BacklogItem`, `PlanningWeek`, `TeamMember`, `WeekMember`, and `MemberTask`, plus domain enums. This layer is where the planning rules live conceptually, including lifecycle constraints and workload limits described in the README.

5. Persistence and infrastructure are isolated in `WeeklyPlanner.Infrastructure`. It contains EF Core `ApplicationDbContext`, migrations, generic repository and unit-of-work abstractions, and command/query handlers. The data store is SQLite-backed in production according to the README, with migrations indicating the schema is managed in code.

6. The system’s main data flow is: Angular feature page -> feature service/store -> HTTP interceptor -> backend controller -> MediatR command/query -> handler -> repository/DbContext -> database. Reads and writes are separated at the use-case level, and the frontend consumes typed models that mirror backend DTOs.

7. The frontend is organized by product area rather than technical layer. Feature folders exist for backlog, planning, team, and home, each with route files and page components. Shared cross-cutting concerns are handled by core services such as API access, theme, toast notifications, user context, and data management.

8. State management on the frontend is centralized under `src/app/store` with separate slices for backlog, planning, and team. Each slice has actions, reducers, effects, and selectors, so page components stay thin and derive data from store state rather than calling the API directly.

9. The planning domain is the center of the product. The backlog module manages work items, the team module manages members, and the planning module orchestrates weekly planning lifecycle views like lead dashboard, member board, review/freeze, progress updates, and historical weeks. These modules together model the rule-driven workflow described in the README.

10. Cross-cutting quality controls are built into the repo. Backend tests include domain unit tests and integration test scaffolding; frontend has component/service/store specs. GitHub Actions workflows separate backend CI, frontend CI, quality gating, and deployment, with production hosting split between Vercel for the frontend and Railway for the API.

11. Operationally, the repository includes deployment-specific configs for both runtimes: Dockerfile for the backend, `vercel.json` and static web app config for the frontend, plus environment files for Angular. Documentation under `docs/` captures architecture, business rules, planning rules, and runbooks, which suggests the repo is designed for maintainability and reviewability as much as for execution.

Main entry points: [`frontend/src/app/features`](https://github.com/yashhhyb/weekly-planerz/tree/main/frontend/src/app/features) (Feature pages), [`backend/WeeklyPlanner.Domain`](https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.Domain) (Domain model), [`backend/WeeklyPlanner.Application`](https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.Application) (Application layer), [`backend/WeeklyPlanner.Infrastructure`](https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.Infrastructure) (Infrastructure)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["Frontend SPA"]
  node_node_frontend_routes["App routes<br/>angular routing<br/>[app.routes.ts]"]
  node_node_frontend_features["Feature pages<br/>ui features"]
  node_node_frontend_services["Core services<br/>client services"]
  node_node_frontend_interceptor{{"HTTP interceptor<br/>client transport<br/>[api.interceptor.ts]"}}
  node_node_frontend_store["State slices<br/>ngrx-like store"]
  node_node_frontend_models["Client models<br/>typed contracts"]
end

subgraph group_group_backend["Backend API"]
  node_node_backend_api["API layer<br/>aspnet controllers<br/>[WeeklyPlanner.API]"]
  node_node_backend_application["Application layer<br/>cqrs orchestration"]
  node_node_backend_domain[("Domain model<br/>business rules")]
  node_node_backend_infra["Infrastructure<br/>persistence and handlers"]
  node_node_backend_db[("Database schema<br/>sqlite schema<br/>[Migrations]")]
end

subgraph group_group_ops["Ops & Delivery"]
  node_node_backend_ci["Backend CI<br/>github workflow<br/>[backend-ci.yml]"]
  node_node_frontend_ci["Frontend CI<br/>github workflow<br/>[frontend-ci.yml]"]
  node_node_quality_gate["Quality gate<br/>github workflow<br/>[quality-gate.yml]"]
  node_node_deploy["Deploy flow<br/>github workflow<br/>[deploy.yml]"]
  node_node_backend_docker["API Dockerfile<br/>container build"]
  node_node_frontend_deploy["Frontend deploy<br/>hosting config<br/>[vercel.json]"]
end

subgraph group_group_docs_tests["Docs & Tests"]
  node_node_backend_tests["Backend tests<br/>unit and integration"]
  node_node_frontend_tests["Frontend specs<br/>component and store tests"]
  node_node_docs["Architecture docs<br/>repo documentation"]
end

node_node_frontend_routes -->|"routes to"| node_node_frontend_features
node_node_frontend_features -->|"uses"| node_node_frontend_services
node_node_frontend_features -->|"reads state"| node_node_frontend_store
node_node_frontend_store -->|"dispatches via"| node_node_frontend_interceptor
node_node_frontend_interceptor -->|"calls"| node_node_backend_api
node_node_frontend_services -->|"uses"| node_node_frontend_models
node_node_frontend_models -.->|"mirrors DTOs"| node_node_backend_application
node_node_backend_api -->|"delegates to"| node_node_backend_application
node_node_backend_api -.->|"protects"| node_node_backend_domain
node_node_backend_application -->|"uses"| node_node_backend_domain
node_node_backend_application -->|"orchestrates"| node_node_backend_infra
node_node_backend_infra -->|"persists to"| node_node_backend_db
node_node_backend_infra -->|"maps"| node_node_backend_domain
node_node_backend_tests -->|"verifies"| node_node_backend_domain
node_node_backend_tests -.->|"scaffolds"| node_node_backend_infra
node_node_frontend_tests -->|"verifies"| node_node_frontend_store
node_node_frontend_tests -->|"verifies"| node_node_frontend_features
node_node_docs -.->|"describes"| node_node_backend_domain
node_node_docs -.->|"describes"| node_node_frontend_features
node_node_backend_ci -->|"runs"| node_node_backend_tests
node_node_frontend_ci -->|"runs"| node_node_frontend_tests
node_node_quality_gate -.->|"includes"| node_node_backend_ci
node_node_quality_gate -.->|"includes"| node_node_frontend_ci
node_node_deploy -->|"packages"| node_node_backend_docker
node_node_deploy -->|"publishes"| node_node_frontend_deploy

click node_node_frontend_routes "https://github.com/yashhhyb/weekly-planerz/blob/main/frontend/src/app/app.routes.ts"
click node_node_frontend_features "https://github.com/yashhhyb/weekly-planerz/tree/main/frontend/src/app/features"
click node_node_frontend_services "https://github.com/yashhhyb/weekly-planerz/tree/main/frontend/src/app/core/services"
click node_node_frontend_interceptor "https://github.com/yashhhyb/weekly-planerz/blob/main/frontend/src/app/core/interceptors/api.interceptor.ts"
click node_node_frontend_store "https://github.com/yashhhyb/weekly-planerz/tree/main/frontend/src/app/store"
click node_node_frontend_models "https://github.com/yashhhyb/weekly-planerz/tree/main/frontend/src/app/models"
click node_node_backend_api "https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.API"
click node_node_backend_application "https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.Application"
click node_node_backend_domain "https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.Domain"
click node_node_backend_infra "https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.Infrastructure"
click node_node_backend_db "https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.Infrastructure/Migrations"
click node_node_backend_tests "https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.Tests"
click node_node_frontend_tests "https://github.com/yashhhyb/weekly-planerz/tree/main/frontend/src/app"
click node_node_docs "https://github.com/yashhhyb/weekly-planerz/tree/main/docs"
click node_node_backend_ci "https://github.com/yashhhyb/weekly-planerz/blob/main/.github/workflows/backend-ci.yml"
click node_node_frontend_ci "https://github.com/yashhhyb/weekly-planerz/blob/main/.github/workflows/frontend-ci.yml"
click node_node_quality_gate "https://github.com/yashhhyb/weekly-planerz/blob/main/.github/workflows/quality-gate.yml"
click node_node_deploy "https://github.com/yashhhyb/weekly-planerz/blob/main/.github/workflows/deploy.yml"
click node_node_backend_docker "https://github.com/yashhhyb/weekly-planerz/tree/main/backend/Dockerfile"
click node_node_frontend_deploy "https://github.com/yashhhyb/weekly-planerz/blob/main/frontend/vercel.json"

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_node_frontend_routes,node_node_frontend_features,node_node_frontend_services,node_node_frontend_interceptor,node_node_frontend_store,node_node_frontend_models toneBlue
class node_node_backend_api,node_node_backend_application,node_node_backend_domain,node_node_backend_infra,node_node_backend_db toneAmber
class node_node_backend_ci,node_node_frontend_ci,node_node_quality_gate,node_node_deploy,node_node_backend_docker,node_node_frontend_deploy toneMint
class node_node_backend_tests,node_node_frontend_tests,node_node_docs toneRose
```

## Components

### Frontend SPA

Angular app organized by product feature, shared services, and centralized state.

- [App routes](https://github.com/yashhhyb/weekly-planerz/blob/main/frontend/src/app/app.routes.ts): angular routing · Root and feature route definitions for the SPA. · `frontend/src/app/app.routes.ts`
- [Feature pages](https://github.com/yashhhyb/weekly-planerz/tree/main/frontend/src/app/features): ui features · Backlog, planning, team, and home pages that form the main user-facing screens. · `frontend/src/app/features`
- [Core services](https://github.com/yashhhyb/weekly-planerz/tree/main/frontend/src/app/core/services): client services · API-facing and cross-cutting services such as theme, toast, user context, and data management. · `frontend/src/app/core/services`
- [HTTP interceptor](https://github.com/yashhhyb/weekly-planerz/blob/main/frontend/src/app/core/interceptors/api.interceptor.ts): client transport · Adds shared request/response behavior around backend calls. · `frontend/src/app/core/interceptors/api.interceptor.ts`
- [State slices](https://github.com/yashhhyb/weekly-planerz/tree/main/frontend/src/app/store): ngrx-like store · Backlog, planning, and team actions, reducers, effects, and selectors. · `frontend/src/app/store`
- [Client models](https://github.com/yashhhyb/weekly-planerz/tree/main/frontend/src/app/models): typed contracts · Frontend data shapes that mirror backend DTOs and API payloads. · `frontend/src/app/models`

### Backend API

ASP.NET Core application split into API, application, domain, and infrastructure layers.

- [API layer](https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.API): aspnet controllers · Backlog, planning, team, and admin controllers plus response shaping and exception middleware. · `backend/WeeklyPlanner.API`
- [Application layer](https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.Application): cqrs orchestration · Commands, queries, DTOs, validators, and validation behavior that coordinate use cases. · `backend/WeeklyPlanner.Application`
- [Domain model](https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.Domain): business rules · Core entities and enums for backlog, planning weeks, team members, and tasks. · `backend/WeeklyPlanner.Domain`
- [Infrastructure](https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.Infrastructure): persistence and handlers · EF Core context, repositories, unit of work, migrations, and MediatR handlers. · `backend/WeeklyPlanner.Infrastructure`
- [Database schema](https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.Infrastructure/Migrations): sqlite schema · Code-first persisted schema managed through EF Core migrations. · `backend/WeeklyPlanner.Infrastructure/Migrations`

### Ops & Delivery

Automation, deployment, and environment configuration.

- [Backend CI](https://github.com/yashhhyb/weekly-planerz/blob/main/.github/workflows/backend-ci.yml): github workflow · Backend validation and quality gate automation. · `.github/workflows/backend-ci.yml`
- [Frontend CI](https://github.com/yashhhyb/weekly-planerz/blob/main/.github/workflows/frontend-ci.yml): github workflow · Frontend validation and quality gate automation. · `.github/workflows/frontend-ci.yml`
- [Quality gate](https://github.com/yashhhyb/weekly-planerz/blob/main/.github/workflows/quality-gate.yml): github workflow · Repository-wide checks that enforce standards before merge. · `.github/workflows/quality-gate.yml`
- [Deploy flow](https://github.com/yashhhyb/weekly-planerz/blob/main/.github/workflows/deploy.yml): github workflow · Deployment automation for frontend and API targets. · `.github/workflows/deploy.yml`
- [API Dockerfile](https://github.com/yashhhyb/weekly-planerz/tree/main/backend/Dockerfile): container build · Backend containerization for deployment. · `backend/Dockerfile`
- [Frontend deploy](https://github.com/yashhhyb/weekly-planerz/blob/main/frontend/vercel.json): hosting config · Frontend deployment configuration for static hosting. · `frontend/vercel.json`

### Docs & Tests

Repository documentation and quality gates.

- [Backend tests](https://github.com/yashhhyb/weekly-planerz/blob/main/backend/WeeklyPlanner.Tests): unit and integration · Domain tests and integration test scaffolding for the backend. · `backend/WeeklyPlanner.Tests`
- [Frontend specs](https://github.com/yashhhyb/weekly-planerz/tree/main/frontend/src/app): component and store tests · Angular component, service, reducer, selector, and effect specs. · `frontend/src/app`
- [Architecture docs](https://github.com/yashhhyb/weekly-planerz/tree/main/docs): repo documentation · System design, business rules, planning rules, API contract, and runbooks. · `docs`

## Connections

- App routes → Feature pages: routes to · Route definitions load feature areas.
- Feature pages → Core services: uses · Pages call shared services for API access and cross-cutting concerns.
- Feature pages → State slices: reads state · Feature pages subscribe to centralized store slices.
- State slices → HTTP interceptor: dispatches via · Effects and services rely on the shared HTTP pipeline.
- HTTP interceptor → API layer: calls · Client requests cross the HTTP boundary into the API.
- Core services → Client models: uses · Services operate on typed client models.
- Client models → Application layer: mirrors DTOs · Frontend models align with backend contract types.
- API layer → Application layer: delegates to · Controllers forward requests into application use cases.
- API layer → Domain model: protects · API boundary exposes domain-backed business operations.
- Application layer → Domain model: uses · Application logic is built around domain entities and rules.
- Application layer → Infrastructure: orchestrates · Commands and queries are executed through infrastructure handlers.
- Infrastructure → Database schema: persists to · EF Core migrations and context manage the database schema.
- Infrastructure → Domain model: maps · Persistence handlers work against domain entities.
- Backend tests → Domain model: verifies · Unit tests exercise core business rules.
- Backend tests → Infrastructure: scaffolds · Integration tests cover backend wiring.
- Frontend specs → State slices: verifies · Specs validate reducers, effects, and selectors.
- Frontend specs → Feature pages: verifies · Component specs cover feature pages.
- Architecture docs → Domain model: describes · Docs capture business rules and planning constraints.
- Architecture docs → Feature pages: describes · Docs explain product flows and UI behavior.
- Backend CI → Backend tests: runs · Backend CI executes backend validation.
- Frontend CI → Frontend specs: runs · Frontend CI executes Angular specs and checks.
- Quality gate → Backend CI: includes · Repository quality gates include backend checks.
- Quality gate → Frontend CI: includes · Repository quality gates include frontend checks.
- Deploy flow → API Dockerfile: packages · Deployment flow builds the API container.
- Deploy flow → Frontend deploy: publishes · Deployment flow configures the frontend host.
