Tattoo

A modern reimplementation of TAT — the course helper app for Taipei Tech students

Help us translate! We use Weblate to manage localizations. Join the project and help us bring Tattoo to your language!

What is this?

Project Tattoo is a work-in-progress Flutter app that helps Taipei Tech (NTUT) students access their course schedules and academic information. This is a ground-up reimplementation with a focus on:

• Modern, maintainable code — Clean architecture and best practices
• Developer-friendly — Easy for future club members to understand and contribute
• Concise implementation — No unnecessary complexity

Getting Started

This project uses mise to manage development tools (Flutter, Java, Ruby).

# Install and activate mise (if not already)
# See: https://mise.jdx.dev/getting-started.html

# Install Flutter, Java, and Ruby
mise install

# Install Flutter dependencies
flutter pub get

# (Optional) Install Ruby dependencies for fastlane
bundle install

# Run the app
flutter run

Firebase & Credentials

This project uses a private Git repository to manage sensitive credentials (signing keys, service accounts, and Firebase configuration files).

1. Request Access: Contact the maintainers for access to the tattoo-credentials repository.
2. Configure .env: Copy .env.example to .env and fill in the MATCH_GIT_URL and MATCH_PASSWORD.
3. Fetch Configs: Run dart run tool/credentials.dart fetch. This will decrypt and place files like google-services.json and keystore.jks in their respective directories.

Firebase Setup (Maintainers only)

If you need to reconfigure Firebase:

1. Install the Firebase CLI.
2. Install the FlutterFire CLI.
3. Run flutterfire configure to update lib/firebase_options.dart.
4. Encrypt and push new config files using dart run tool/credentials.dart encrypt <file> <path_in_repo>.

HTML Snapshot Capture

Developers can capture raw NTUT HTML/XML responses for parser work:

# List supported Service-layer capture presets
dart run tool/html_snapshot.dart list

# Capture a known page using test/test_config.json
dart run tool/html_snapshot.dart capture student_query.profile -m "profile parser baseline"

# Capture multiple known pages
dart run tool/html_snapshot.dart capture student_query.profile course.semester_list -m "semester start samples"

# Capture every preset that can be resolved without explicit IDs
dart run tool/html_snapshot.dart capture -a -m "routine parser refresh"

# Capture a custom request with the same service client settings
dart run tool/html_snapshot.dart raw QryBasisData.jsp --service student_query -m "custom profile page check"

The tool reads test/test_config.json. If the file is missing, copy test/test_config.json.example to test/test_config.json and fill in NTUT_TEST_USERNAME and NTUT_TEST_PASSWORD.

Captured files are written under tmp/html_snapshot/ with the service name prefixed in the file name. Each file starts with a commented metadata block containing a raw-capture warning, preset, request_url, fetchtime, message, and a parser expected-result TODO; use -m/--message to describe why the sample was kept. If no message is provided, the tool writes a message: TODO placeholder that must be replaced before promotion. The parser expected-result TODO is separate from message and may remain until the HTML-based test code is complete. This directory is local-only and ignored by git. Do not commit raw captures; de-identify them before promoting any sample into a fixture or documentation, and do not submit a promoted snapshot without a meaningful message. capture -a skips presets that require explicit identifiers, such as a course, teacher, classroom, or syllabus ID.

When adding new Service-layer parser requests, add or update capture presets in tool/html_snapshot/presets.dart.

Portal Endpoints Scraper

Developers can scrape all available subsystem endpoints and their corresponding apOu SSO codes from the NTUT portal:

# Scrape and print as plain text table using test/test_config.json
dart run tool/scrape_portal.dart

# Scrape and print as formatted JSON
dart run tool/scrape_portal.dart -f json

# Scrape and write output directly to a JSON file
dart run tool/scrape_portal.dart -f json -o tmp/portal_endpoints.json

# Pass username via command line and password via environment variable
NTUT_PORTAL_PASSWORD=<password> dart run tool/scrape_portal.dart -u <username>

The scraper logs in to the NTUT portal using the mobile App User-Agent flow to bypass the web login captcha, fetches the portal tree page (aptreeMain.do), extracts the SSO targets, and deduplicates the results automatically.

Command Options & Usage

Run the tool using Dart:

dart run tool/scrape_portal.dart [arguments]

Available Arguments:

• -u, --username: NTUT portal username (can also be set via NTUT_PORTAL_USERNAME or NTUT_TEST_USERNAME environment variables).
• -c, --config: Path to config JSON (defaults to test/test_config.json if credentials aren't passed via CLI or env variables).
• -f, --format: Output format, either text (default) or json.
• -o, --output: Path to write the output content. Prints to standard output if omitted.
• -h, --help: Displays help info.

Password must be supplied either via the config file or via the NTUT_PORTAL_PASSWORD / NTUT_TEST_PASSWORD environment variables to prevent command history leaks.

Local Development

Android SDK: Install Android Studio or let Flutter download SDK components automatically on first build.

VS Code users: See .vscode/README.md for project-specific setup instructions.

Contributors: See CONTRIBUTING.md for commit and branch guidelines.

Project Context

Check AGENTS.md to see detailed architecture notes, implementation status, and future plans.

This project exists alongside two other implementations:

• NEO-TAT/tat_flutter — The original TAT app
• NTUT-NPC/tat2_flutter (QAQ) — A feature-rich alternative with offline mode, smart session management, and advanced UI

Project Tattoo aims to take lessons learned from both and create a clean, maintainable foundation for future development.

License

Copyright (C) 2026 NTUT Programming Club (NTUT-NPC)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

See LICENSE for details.