mirror of
https://github.com/aaronpo97/the-biergarten-app.git
synced 2026-06-01 01:54:00 +00:00
154 lines
4.6 KiB
Markdown
154 lines
4.6 KiB
Markdown
# The Biergarten App
|
|
|
|
The Biergarten App is a full-stack directory and discovery platform for
|
|
breweries. It features a robust user authentication system, a searchable
|
|
database of brewery locations, and a custom offline data-generation pipeline
|
|
that uses LLMs (Llama.cpp) and Wikipedia to synthesize realistic seed data.
|
|
|
|
It features:
|
|
|
|
- A .NET backend (Web API + database migrations/seed) under `web/backend/`
|
|
- A server-rendered React website (React Router + Vite) under `web/frontend/`
|
|
- A C++20 “pipeline” CLI for generating seed data under `tooling/pipeline/`
|
|
|
|
Specialized documentation (setup, architecture, docker, testing, diagrams, and
|
|
pipeline notes) lives under `docs/`.
|
|
|
|
## Documentation (Start Here)
|
|
|
|
Website + backend (active stack):
|
|
|
|
- [Getting Started](docs/website/getting-started.md)
|
|
- [Architecture](docs/architecture.md)
|
|
- [Docker Guide](docs/website/docker.md)
|
|
- [Testing](docs/website/testing.md)
|
|
- [Environment Variables](docs/website/environment-variables.md)
|
|
- [Token Validation](docs/website/token-validation.md)
|
|
|
|
Data generation pipeline (C++):
|
|
|
|
- [Pipeline README](docs/pipeline/README.md)
|
|
- [Ethics & Known Issues](docs/pipeline/ETHICS-AND-KNOWN-ISSUES.md)
|
|
|
|
## Diagrams
|
|
|
|
- [Architecture](docs/website/diagrams-out/architecture.svg)
|
|
- [Deployment](docs/website/diagrams-out/deployment.svg)
|
|
- [Authentication Flow](docs/website/diagrams-out/authentication-flow.svg)
|
|
- [Database Schema](docs/website/diagrams-out/database-schema.svg)
|
|
|
|
## Current Status
|
|
|
|
Active areas in the repository:
|
|
|
|
- .NET 10 backend (layered architecture) + SQL Server
|
|
- React 19 website (React Router 7 + Vite)
|
|
- Shared Biergarten theme system + Storybook coverage
|
|
- Auth flows and account/email integration (local Mailpit in dev compose)
|
|
- Data generation pipeline with C++ and Llama.cpp
|
|
|
|
Archived/reference areas:
|
|
|
|
- `archive/next-js-web-app/` contains an older Next.js frontend retained for
|
|
reference
|
|
|
|
## Tech Stack
|
|
|
|
- **Backend**: .NET 10, ASP.NET Core, SQL Server 2022, DbUp
|
|
- **Frontend**: React 19, React Router 7, Vite 7, Tailwind CSS 4, DaisyUI 5
|
|
- **UI Documentation**: Storybook 10, Vitest browser mode, Playwright
|
|
- **Testing**: xUnit, Reqnroll (BDD), FluentAssertions, Moq
|
|
- **Infrastructure**: Docker, Docker Compose
|
|
- **Security**: Argon2id password hashing, JWT access/refresh/confirmation
|
|
tokens
|
|
- **Data Pipeline**: C++20, CMake, Boost, libcurl, SQLite, llama.cpp
|
|
|
|
## Quick Start
|
|
|
|
For full setup details, use [Getting Started](docs/website/getting-started.md).
|
|
This section is the shortest path to a working dev environment.
|
|
|
|
### Backend (Docker)
|
|
|
|
```bash
|
|
git clone https://github.com/aaronpo97/the-biergarten-app
|
|
cd the-biergarten-app
|
|
|
|
cp web/.env.example web/.env.dev
|
|
docker compose --env-file web/.env.dev -f web/docker-compose.dev.yaml up --build -d
|
|
```
|
|
|
|
Backend access:
|
|
|
|
- API Swagger: http://localhost:8080/swagger
|
|
- Health Check: http://localhost:8080/health
|
|
- Mailpit UI (dev SMTP): http://localhost:8025
|
|
|
|
### Frontend (Node)
|
|
|
|
```bash
|
|
cd web/frontend
|
|
npm install
|
|
API_BASE_URL=http://localhost:8080 SESSION_SECRET=dev-secret-change-me npm run dev
|
|
```
|
|
|
|
Optional frontend tools:
|
|
|
|
```bash
|
|
cd web/frontend
|
|
npm run storybook
|
|
npm run test:storybook
|
|
npm run test:storybook:playwright
|
|
```
|
|
|
|
## Repository Structure
|
|
|
|
```text
|
|
web/
|
|
backend/ .NET API + domain/service/infrastructure + DB projects
|
|
frontend/ React Router website + Storybook + Playwright/Vitest
|
|
|
|
tooling/
|
|
pipeline/ C++20 seed-data generation CLI (CMake)
|
|
|
|
docs/
|
|
architecture.md High-level architecture overview
|
|
website/ Backend/frontend setup, docker, testing, diagrams
|
|
pipeline/ Pipeline docs, ethics notes, PlantUML diagrams
|
|
|
|
archive/
|
|
next-js-web-app/ Older Next.js frontend (reference only)
|
|
|
|
misc/
|
|
raw-data/ Source CSV/JSON fixtures used during development
|
|
```
|
|
|
|
## Testing
|
|
|
|
Run the backend test stack with Docker:
|
|
|
|
```bash
|
|
docker compose --env-file web/.env.test -f web/docker-compose.test.yaml up --abort-on-container-exit
|
|
```
|
|
|
|
See [Testing](docs/website/testing.md) for the full command list.
|
|
|
|
## Configuration
|
|
|
|
Common active variables:
|
|
|
|
- Backend/Docker: `DB_SERVER`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`,
|
|
`ACCESS_TOKEN_SECRET`, `REFRESH_TOKEN_SECRET`, `CONFIRMATION_TOKEN_SECRET`,
|
|
`WEBSITE_BASE_URL`
|
|
- Frontend runtime: `API_BASE_URL`, `SESSION_SECRET`, `NODE_ENV`
|
|
|
|
See [Environment Variables](docs/website/environment-variables.md) for details.
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|