# w3barsi/senatoriables architecture

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

- Interactive diagram: https://gitdiagram.com/w3barsi/senatoriables
- Repository: https://github.com/w3barsi/senatoriables

## Overview

##### Project type and purpose
- This is a full-stack web application starter template (TanStarter) built on React 19 + React Compiler, TanStack Start (SSR framework) with Router & Query, Tailwind CSS + shadcn/ui for styling, Drizzle ORM for Postgres-based data persistence, and Better Auth for OAuth-based authentication.
- It provides an end-to-end example: file-based routing in `src/routes`, tRPC-powered APIs in `src/server/trpc`, and a client-side React app in `src/client.tsx`.

##### File structure
- Top-level:
- `src/client.tsx`, `src/ssr.tsx` → client & SSR entry points
- `src/routes/` → TanStack file-based route definitions & UI components
- `src/lib/` → shared client libs (auth, UI components, hooks, middleware, utils)
- `src/server/` → tRPC router, auth setup, database init
- `docker-compose.yml`, `.env.example`, `drizzle.config.ts` → database and ORM configuration
- Key patterns:
- File-based routing → mapping URL ↔ React components
- RPC pattern (tRPC) → client & server share type-safe contract
- Layered architecture → UI → hooks → business logic → data access

##### README for architectural insights
- Confirms stack: React Compiler, TanStack Start (SSR + routing), TanStack Query (data fetching), Drizzle ORM → Postgres, Better Auth (OAuth).
- Mentions OAuth providers (GitHub, Google, Discord).
- Describes development scripts (pnpm dev, pnpm db push).

##### Main components and their interactions
a. Frontend (Browser)
- React Compiler-built UI
- TanStack Router handles client-side navigation (file routes → React pages)
- TanStack Query for data fetching & caching
- UI layer: shadcn/ui + Tailwind components (in `src/lib/components`)
- Hooks & middleware (e.g., `use-media-query`, `auth-guard`)
b. API layer (tRPC client/server)
- Client: `src/lib/trpc/react.ts` → `useQuery` / `useMutation` calls
- Server: `src/server/trpc/init.ts`, `router.ts`, `routes/*.ts` define RPC procedures
- Auth guard middleware wraps protected procedures
c. Backend & Persistence
- Drizzle ORM (`drizzle.config.ts`, `src/types/db.ts`) → Postgres via Docker
- Better Auth (`src/server/auth.ts`) → user/session management with external OAuth
d. External Services
- OAuth providers (GitHub, Google, Discord) for authentication

##### Architectural patterns & design principles
- Separation of concerns: UI, routing, data layer, authentication
- Type-safe end-to-end contracts via TypeScript + tRPC
- File-based routing → convention over configuration
- Middleware pattern for auth enforcement
- Infrastructure as code: Docker Compose for database

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Browser UI"
        direction TB
        ClientEntry["Client Entry Point"]:::frontend
        FileRoutes["File-based Routes"]:::frontend
        RootRoute["Root Route Component"]:::frontend
        UIComponents["UI Components"]:::frontend
        Hooks["Custom Hooks"]:::frontend
        Middleware["Middleware (Auth Guard)"]:::frontend
        TRPCClient["tRPC Client Setup"]:::frontend
        TRPCRoot["tRPC Root Provider"]:::frontend
        AuthClient["Auth Client Helpers"]:::frontend
        Styles["Styles (Tailwind CSS)"]:::frontend
    end

    %% Server Layer
    subgraph "SSR / Node.js Server"
        direction TB
        SSREntry["SSR Entry Point"]:::backend
        AppRouter["Application Router Config"]:::backend
        GeneratedRoutes["Generated Route Tree"]:::backend
        AuthAPIRoute["Auth API Route"]:::backend
        TRPCAPIRoute["tRPC API Route"]:::backend
        AuthModule["Server-side Auth Module"]:::backend
        TRPCInit["tRPC Server Initialization"]:::backend
        TRPCRouter["tRPC Server Router"]:::backend
        TestProcedure["tRPC Proc: test.tsx"]:::backend
        VoteProcedure["tRPC Proc: vote.tsx"]:::backend
    end

    %% Database Layer
    subgraph Database
        direction TB
        DrizzleConfig["drizzle.config.ts"]:::data
        DBTypes["src/types/db.ts"]:::data
        Postgres["PostgreSQL (Docker Compose)"]:::data
    end

    %% External Services
    subgraph "External OAuth Providers"
        direction TB
        OAuthGH["GitHub"]:::external
        OAuthGoogle["Google"]:::external
        OAuthDiscord["Discord"]:::external
    end

    %% Data Flows
    ClientEntry -->|"initial render"| SSREntry
    SSREntry -->|"serves pages"| ClientEntry
    FileRoutes -->|"defines pages"| AppRouter
    AppRouter --> GeneratedRoutes
    RootRoute --> FileRoutes
    UIComponents --> FileRoutes
    Hooks --> FileRoutes
    Middleware --> TRPCRoot
    Styles --> ClientEntry
    TRPCClient -->|"RPC calls /trpc/*"| TRPCInit
    TRPCClient --> TRPCRoot
    TRPCRoot --> SSREntry
    AuthClient --> TRPCRoot
    AuthAPIRoute --> TRPCInit
    TRPCAPIRoute --> TRPCInit
    AuthModule --> TRPCInit
    TRPCInit --> TRPCRouter
    TRPCRouter --> TestProcedure
    TRPCRouter --> VoteProcedure
    TestProcedure --> DrizzleConfig
    VoteProcedure --> DBTypes
    TRPCInit --> Postgres
    AuthModule --> OAuthGH
    AuthModule --> OAuthGoogle
    AuthModule --> OAuthDiscord

    %% Click Events
    click ClientEntry "https://github.com/w3barsi/senatoriables/blob/main/src/client.tsx"
    click SSREntry "https://github.com/w3barsi/senatoriables/blob/main/src/ssr.tsx"
    click FileRoutes "https://github.com/w3barsi/senatoriables/tree/main/src/routes/"
    click RootRoute "https://github.com/w3barsi/senatoriables/blob/main/src/routes/__root.tsx"
    click UIComponents "https://github.com/w3barsi/senatoriables/tree/main/src/lib/components/ui/"
    click Hooks "https://github.com/w3barsi/senatoriables/blob/main/src/hooks/use-media-query.ts"
    click Middleware "https://github.com/w3barsi/senatoriables/blob/main/src/lib/middleware/auth-guard.ts"
    click TRPCClient "https://github.com/w3barsi/senatoriables/blob/main/src/lib/trpc/react.ts"
    click TRPCRoot "https://github.com/w3barsi/senatoriables/blob/main/src/lib/trpc/root-provider.tsx"
    click AuthClient "https://github.com/w3barsi/senatoriables/blob/main/src/lib/auth-client.ts"
    click Styles "https://github.com/w3barsi/senatoriables/blob/main/src/lib/styles/app.css"
    click AppRouter "https://github.com/w3barsi/senatoriables/blob/main/src/router.tsx"
    click GeneratedRoutes "https://github.com/w3barsi/senatoriables/blob/main/src/routeTree.gen.ts"
    click AuthAPIRoute "https://github.com/w3barsi/senatoriables/blob/main/src/routes/api/auth.$.ts"
    click TRPCAPIRoute "https://github.com/w3barsi/senatoriables/blob/main/src/routes/api/trpc.$.tsx"
    click AuthModule "https://github.com/w3barsi/senatoriables/blob/main/src/server/auth.ts"
    click TRPCInit "https://github.com/w3barsi/senatoriables/blob/main/src/server/trpc/init.ts"
    click TRPCRouter "https://github.com/w3barsi/senatoriables/blob/main/src/server/trpc/router.ts"
    click TestProcedure "https://github.com/w3barsi/senatoriables/blob/main/src/server/trpc/routes/test.tsx"
    click VoteProcedure "https://github.com/w3barsi/senatoriables/blob/main/src/server/trpc/routes/vote.tsx"
    click DrizzleConfig "https://github.com/w3barsi/senatoriables/blob/main/drizzle.config.ts"
    click DBTypes "https://github.com/w3barsi/senatoriables/blob/main/src/types/db.ts"
    click Postgres "https://github.com/w3barsi/senatoriables/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#bfdfff,stroke:#333,stroke-width:1px
    classDef backend fill:#c8e3b0,stroke:#333,stroke-width:1px
    classDef data fill:#fdd38d,stroke:#333,stroke-width:1px
    classDef external fill:#f8c8c8,stroke:#333,stroke-width:1px
```
